# Why AI coding agents write outdated web code, and how Modern Web Guidance fixes it

_Chrome, Edge, Firefox and MDN now ship expert guidance for coding agents. What it changes and whether it works._

> AI coding agents default to legacy web patterns. Modern Web Guidance 1.0 steers them to modern browser APIs. The ten common mistakes, how it works, the evals and how to install it.

- Tags: News, AI
- Published: 2026-11-19
- Category: News
- Author: insidethebox
- Topics: AI, Engineering
- Reading time: 4 min
- Source: https://www.insidethebox.dev/insights/modern-web-guidance-ai-coding-agents

Ask an AI coding agent for a modal and you'll often get a fixed overlay, a click-outside handler and a hand-written focus trap: code from a decade ago, when browsers had no better option. On 10 November 2026 the Chrome team released Modern Web Guidance 1.0 to fix that.

For the animated version, see our [Modern Web Guidance guide](/guides/modern-web-guidance).

## The problem: agents learn from old code

Language models learn from the code that already exists, and most web code was written before today's platform features shipped. So agents reach for libraries and workarounds the browser no longer needs. Chrome describes the result as "bloated JavaScript" for jobs the platform does natively, and says it has catalogued "hundreds of verified AI knowledge gaps".

## What Modern Web Guidance is

Modern Web Guidance is a set of skills for coding agents plus a command-line tool. Its README says it is stewarded by the Google Chrome, Microsoft Edge, Mozilla Firefox and MDN teams with the web community, and Chrome's announcement describes Firefox and Edge as joining the effort. It is free and open source (Apache 2.0).

It covers 262 modern web features (140 in CSS and layout, 85 in JavaScript and APIs, 37 in HTML and the DOM) and 204 real-world use cases, from accessibility and forms to performance, security, passkeys, the browser's built-in AI and WebMCP.

## The ten things AI gets wrong

Chrome's team published the mistakes it sees most. In short:

1. **Focus management:** manual tab traps and `aria-modal` on custom modals, instead of a modal `<dialog>` and `inert` on the background.
2. **Reduced motion:** smooth scrolling and animations for everyone, instead of gating them behind `prefers-reduced-motion`.
3. **Form validation:** JavaScript `blur` validation and placeholder-only hints, instead of `:user-invalid` with `aria-invalid` and hints linked by `aria-describedby`.
4. **Swipe and touch:** `touchmove` listeners with custom physics, instead of CSS Scroll Snap and scroll-driven animations.
5. **Dialogs and popovers:** fixed overlays and back-button hacks, instead of `popover`, `<dialog>` and `@starting-style` transitions.
6. **Dark mode:** a binary toggle that ignores the system setting, instead of `color-scheme` and `light-dark()`.
7. **Responsiveness:** `setTimeout()` queues, instead of `scheduler.yield()` and `content-visibility`.
8. **Layout shifts:** anti-flicker snippets and static `vh` units, instead of `blocking="render"`, `dvh` and `aspect-ratio`.
9. **DOM XSS:** hand-rolled sanitizers and eagerly bundled DOMPurify, instead of native `setHTML()` and a strict CSP.
10. **Passkeys:** hand-written Base64URL helpers, instead of the WebAuthn JSON helpers such as `parseCreationOptionsFromJSON()`.

Every one of these makes a site heavier, less accessible or less secure than it needs to be.

## How it works

Installed in a coding agent, the guidance works like a reference shelf. Before writing code, the agent searches for the guide that fits the task, for example `modern-web-guidance search "animate a dialog modal backdrop"`, and loads just that guide into its context. The guides are short by design: Chrome runs evals and removes anything models already know.

It is careful about older browsers. Features that only add polish are ignored where they aren't supported, critical behaviour gets a small fallback (under 50 lines) or a polyfill loaded only when needed, compatibility comes from the Baseline project's data, and experimental features stay off until you opt in.

Version 1.0 can also modernize existing code: it scans HTML, CSS, JavaScript and `package.json` for safe upgrades. The first release uses static analysis on a limited set of patterns.

## Does it work?

Each guide defines expectations, and Chrome runs the same prompt through an agent with and without the guidance. On its eval suite, unguided agents pass about **52%** of the checks and guided agents about **91%** (as of 9 November 2026). The results are on a [public dashboard](https://googlechrome.github.io/modern-web-guidance-src/).

Teams quoted in Chrome's announcement report:

- **WeTV (Tencent):** a coding agent in its release pipeline now resolves 90% of failed performance checks on its own, and fixing them takes 30 minutes instead of four hours.
- **note inc.:** pass rates on modern web checks rose from 61% to 94% across 180 runs.
- **Policybazaar:** 92% less manual auditing across about 30 landing pages.

These are Chrome's and its partners' figures. As with any tool, measure it on your own codebase.

## How to install it

You need Node.js. Run `npx modern-web-guidance@latest install` and the wizard asks which coding agent you use. It is also in the plugin marketplaces of Claude Code, Codex, Cursor, Antigravity, GitHub Copilot, WebStorm, Kimi Code and Grok Build. To modernize a project, ask your agent: `/modern-web-guidance Modernize the code in this directory`. All the commands, with copy buttons, are in [our guide](/guides/modern-web-guidance#install).

## What it means for your website

Code built on the platform's own features is lighter, faster and more accessible: less JavaScript to download, components keyboards and screen readers already understand, and security features such as passkeys and safe HTML handling built in. If your site was built a few years ago, a modernization pass is often the cheapest speed and accessibility win available.

We build with modern web APIs by default. [See how we build websites](/services/website-development) or [ask us to review yours](/contact).

## Sources

- [Modern Web Guidance on GitHub](https://github.com/GoogleChrome/modern-web-guidance) (README)
- [Modern Web Guidance 1.0: the web platform expertise your coding agent is missing](https://developer.chrome.com/blog/modern-web-guidance-v1) (Chrome for Developers, 10 Nov 2026)
- [Top 10 things AI gets wrong in web development](https://developer.chrome.com/blog/top-10-things-ai-gets-wrong-in-web-dev) (Chrome for Developers, 11 Nov 2026)
- [Beyond code generation: using Modern Web Guidance for continuous developer learning](https://developer.chrome.com/blog/beyond-code-generation) (Chrome for Developers)
- [Modern Web Guidance documentation](https://developer.chrome.com/docs/modern-web-guidance) (Chrome for Developers)
- [Eval dashboard](https://googlechrome.github.io/modern-web-guidance-src/) (GoogleChrome)
