Area
What agents write
With the guidance
Dialogs & popovers
- position: fixed overlay
- click-outside handler
- popstate back-button hack
- <dialog> / popover
- native back-button close
- @starting-style + transition-behavior
Form validation
- blur-event validation in JS
- placeholder-only hints
- :user-invalid + aria-invalid
- hints linked with aria-describedby
Swipe & touch
- touchmove listeners
- custom scroll physics
- CSS Scroll Snap
- overscroll-behavior-x: none
- scroll-driven animations
Dark mode
- binary light/dark toggle
- no OS default
- <meta name="color-scheme">
- light-dark()
Responsiveness
- setTimeout() queues
- display: none on hidden views
- scheduler.yield()
- content-visibility: auto
DOM XSS
- hand-rolled DOMParser sanitizer
- eagerly bundled DOMPurify
- setHTML()
- lazy-loaded DOMPurify fallback
- strict-dynamic CSP
Also covered: Responsiveness · DOM XSS
From Chrome’s “Top 10 things AI gets wrong in web dev”
By insidethebox · · 4 min read
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.
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.
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:
- Focus management: manual tab traps and
aria-modalon custom modals, instead of a modal<dialog>andinerton the background. - Reduced motion: smooth scrolling and animations for everyone, instead of gating them behind
prefers-reduced-motion. - Form validation: JavaScript
blurvalidation and placeholder-only hints, instead of:user-invalidwitharia-invalidand hints linked byaria-describedby. - Swipe and touch:
touchmovelisteners with custom physics, instead of CSS Scroll Snap and scroll-driven animations. - Dialogs and popovers: fixed overlays and back-button hacks, instead of
popover,<dialog>and@starting-styletransitions. - Dark mode: a binary toggle that ignores the system setting, instead of
color-schemeandlight-dark(). - Responsiveness:
setTimeout()queues, instead ofscheduler.yield()andcontent-visibility. - Layout shifts: anti-flicker snippets and static
vhunits, instead ofblocking="render",dvhandaspect-ratio. - DOM XSS: hand-rolled sanitizers and eagerly bundled DOMPurify, instead of native
setHTML()and a strict CSP. - 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 (opens in a new tab).
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.
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 or ask us to review yours.
Sources
- Modern Web Guidance on GitHub (opens in a new tab) (README)
- Modern Web Guidance 1.0: the web platform expertise your coding agent is missing (opens in a new tab) (Chrome for Developers, 10 Nov 2026)
- Top 10 things AI gets wrong in web development (opens in a new tab) (Chrome for Developers, 11 Nov 2026)
- Beyond code generation: using Modern Web Guidance for continuous developer learning (opens in a new tab) (Chrome for Developers)
- Modern Web Guidance documentation (opens in a new tab) (Chrome for Developers)
- Eval dashboard (opens in a new tab) (GoogleChrome)
Topics: AI · Engineering
Related insights
[All insights]What it takes to run AI agents in production
Demos are easy. Tuesdays are hard.
GuidesWhy your website still matters in the age of AI search
Assistants quote someone. Make it you.
GuidesJPEG XL is back: what the format is and why every browser now shows it
Chrome, Edge and Firefox switched it on in October 2026. Here is what changes for your website.
News