TL;DR
Modern Web Guidance (MWG, GoogleChrome/modern-web-guidance) is an agent skill plus a small offline CLI that gives coding agents like Claude Code, Codex, Cursor and Copilot curated, browser-engineer-written guides on modern HTML, CSS and JavaScript. On a frontend task, the agent searches the local guide library and writes code against the relevant guides, so you get a native <dialog> instead of a div overlay with z-index: 9999.
Not run by us: our container test lab returned no result today (it reported no valid artifacts), so nothing in this review comes from running the CLI ourselves. Everything below is from the repositories, the Chrome for Developers docs and blog, the public eval dashboard, release notes and public coverage.
Facts as of November 17, 2026:
- 21,526 GitHub stars and 844 forks on the distribution repo
GoogleChrome/modern-web-guidance. The source repo,GoogleChrome/modern-web-guidance-src, where the guides, evals and graders live, has 8,231 stars and is on GitHub’s weekly trending list. - 312 open issues on the source repo (issues only). The distribution repo has its issue tracker turned off; bugs go to
-src. - License: Apache-2.0. Free; no account or API key.
- Latest release: v1.0.1, published November 16, 2026. Version 1.0.0 shipped November 10, 2026, after a preview that started at Google I/O in May.
- The npm package
modern-web-guidanceneeds Node.js 22 or newer. - Stewarded by Google Chrome, Microsoft Edge, Mozilla Firefox and MDN. Apple/WebKit has no seat.
Verdict: MWG is the most credible “fix your agent’s stale frontend habits” skill available, because it is written and reviewed by browser engineers and it publishes its own A/B evals. Install it if your agents write UI code. Do not treat it as an accessibility or cross-browser guarantee: the project itself says agents may skip or half-read a guide, and the headline numbers are Google’s own.
Quick Reference
| Field | Value |
|---|---|
| What it is | Agent skill + offline search CLI over ~200 expert-written web platform guides |
| Install (recommended) | npx modern-web-guidance@latest install |
| Try without installing | npx modern-web-guidance@latest search "animate a dialog modal backdrop" |
| Agents | Claude Code, Codex, Cursor, Copilot CLI, Gemini CLI, Antigravity, WebStorm, Goose, Grok, Kimi Code, anything that reads skills |
| Coverage (v1.0.0 notes) | 203 use-case guides, 250 web platform features |
| Default browser target | Baseline Widely available |
| Search | Local embeddings + BM25, fully offline |
| Runtime | Node.js ≥ 22 |
| License | Apache-2.0 |
| Docs | developer.chrome.com/docs/modern-web-guidance |
What Problem Modern Web Guidance Solves
Ask a frontier coding model for a modal, tooltip or accordion and it will usually produce something that works, the 2017 way: a div overlay, a manual Escape listener, 100vh, a JavaScript positioning library, Moment.js for date math. Training data is dominated by a decade of jQuery tutorials and old Stack Overflow answers.
The browser has moved on: <dialog>, the Popover API, CSS anchor positioning, @starting-style, container queries, scheduler.yield(), Temporal. Philip Walton’s 1.0 launch post says a web expert reviewing AI-generated code “can almost always find ways to make the code faster, more accessible, or more secure.”
MWG’s answer is deliberately unglamorous: no fine-tuning, no hosted service. It is a folder of Markdown guides, a local search command and a SKILL.md telling the agent to use them before it writes UI code.
How It Works
The skill file is short and opinionated. Its description says “MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks” — modals, forms, Core Web Vitals, passkeys, dates — and not for SQL, CI/CD or Docker. It prescribes four steps:
- Search with a 2–5 word English query for one capability, such as
"light dismiss dialog", with framework names stripped out. - Retrieve the full guide by ID, plus any broader discipline guide (
html,css,accessibility). - Verify the code against the guide, including fallbacks.
- Disclose: end the reply with a
### Modern Web Guidancesection naming each guide applied and quoting the rule that mattered — a useful paper trail for human reviewers.
Here is what a search returns, taken from the official get-started docs (trimmed):
[
{"id":"light-dismiss-a-dialog",
"description":"Create a modal dialog that can be closed via light dismiss...",
"category":"ui-behaviors","featuresUsed":["<dialog closedby>"],
"tokenCount":1085,"similarity":0.7076},
{"id":"animate-to-from-top-layer",
"description":"Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer.",
"featuresUsed":["::backdrop","<dialog>","overlay","Popover","@starting-style","transition-behavior"],
"tokenCount":1541,"similarity":0.6842}
]
Note the tokenCount field: guides are sized so the agent knows what it is loading, and the README says evals are used to prune content models already know. retrieve "animate-to-from-top-layer" then prints the full guide.
What’s in the library
Coverage spans UX (view transitions, scroll-driven animation), CSS layout (container queries, subgrid, oklch, text-wrap), performance (INP, fetch priority, speculation rules), forms (customizable <select>, :user-invalid, autofill-correct forms), accessibility, security (passkeys, Trusted Types, the Sanitizer API), JavaScript (Temporal, structuredClone), web components and Chrome’s built-in AI APIs. Version 1.0.0 added eight UI component guides, including accordion, app menus, carousel and navbar.
Browser targets: Baseline
MWG reads your browser target from your agent instructions file. Add a line like this to AGENTS.md or CLAUDE.md:
This project's Baseline target is Baseline 2024.
If you set nothing, it defaults to Baseline Widely available (interoperable across major engines for at least 30 months). Guides for single-engine (“volatile”) and origin-trial features stay locked unless you opt in via .mwgrc:
npx modern-web-guidance@latest set-allow-volatile-features
npx modern-web-guidance@latest set-allow-origin-trials
What’s New in 1.0
According to the v1.0.0 release notes and the launch post:
legacy-scan, a modernization scanner.npx modern-web-guidance@latest legacy-scan .statically checks HTML, CSS, JavaScript andpackage.jsonfor legacy patterns and maps each finding to a guide. The notes say it covers “roughly 20% of guides that have deterministic legacy rules today.” In an agent:/modern-web-guidance Modernize the code in this directory.- Smaller offline search: a zero-dependency embedding model plus BM25 replaced TensorFlow.js; the npm download dropped from 23.5 MB to 8.8 MB.
- Cross-browser governance: GOVERNANCE.md defines six owner seats — two Chrome, one each for Edge and Mozilla, two independent (one open). Every guide gets tech-lead sign-off; user-facing guides get an accessibility review.
- Public evals on the eval dashboard.
v1.0.1 (November 16) is a content release: a new js guide, a lang attribute rule for translated content, and fixes to the anchor positioning and autofill guides.
Installation
The recommended path is the CLI, which also enables automatic updates:
npx modern-web-guidance@latest install # interactive wizard
npx modern-web-guidance@latest install --choose # pick skills (e.g. Chrome extension dev)
npx modern-web-guidance@latest update # upgrade from the preview
Or install through your agent’s plugin system. From the official docs:
# Claude Code
claude plugin marketplace add GoogleChrome/modern-web-guidance
claude plugin install modern-web-guidance@googlechrome
# GitHub CLI / generic skills installer
gh skill install GoogleChrome/modern-web-guidance
Codex, Gemini CLI, Copilot CLI, Goose, Grok, Kimi Code, WebStorm and Antigravity have their own one-liners on the same page. Most non-CLI paths don’t auto-update, which matters for a corpus that changes weekly. search and retrieve work through npx with nothing installed, so you can judge the guides first.
What the Evals Say (Google’s Numbers)
All numbers in this section are published or reported by others. We did not reproduce them.
The eval dashboard runs nightly A/B jobs: Claude Code, Codex CLI and Antigravity CLI get identical tasks on a starter web app, once with MWG installed and once without. Playwright then opens the finished app in a real browser and checks DOM, styles and source against each requirement. Task prompts never mention MWG, so the agent has to decide on its own to use it.
- The get-started docs say early results show an average 37 percentage point improvement in adherence to best practices with MWG installed.
- Search Engine Journal read the dashboard on November 10 and reported 88% of automated checks passing with guidance vs 56% without, based on nightly runs completed November 8 (199 to 215 tasks per agent). It also noted that in most recent suites, guided runs were slower and used more tokens. The dashboard says its accessibility checks cover five dimensions (keyboard, focus and inert, reduced motion and contrast, ARIA, form labels) and are not a full WCAG audit. To avoid penalizing valid alternative code, graders check rendered behavior and computed accessibility semantics, not specific markup.
Partner case studies
Google’s launch post highlights four teams. All figures are the companies’ own, as published by Chrome:
- note inc. (Japan): across 180 runs on its production codebase, modern-web pass rates went from 61% to 94%. Per SEJ, scores rose once the skill was installed and rose again when prompts named it (one agent: 60.8% → 76.5% → 94.0%).
- MetaMask runs MWG as a review bot on every PR to its open-source extension, with a three-line prompt. Chrome’s summary: about 480 PRs in five weeks, comments on 64, 43 findings fixed, median 15 minutes to fix. SEJ’s reading of the detailed post: 102 issues raised, 43 fully resolved, 16 declined or false positives, 20 unaddressed.
- Policybazaar and WeTV (Tencent) report 87–92% time reductions, but those pair MWG with Chrome DevTools MCP, so they are not MWG-only numbers.
The MetaMask pattern is the most transferable: MWG as a reviewer, not just a writer. A DEV Community write-up quotes a developer whose writer agent slipped back into old habits on long prompts, while a reviewer agent with the skill caught the regressions.
Community Reaction
The launch drew discussion on Hacker News (a Show HN titled “Get your coding agent off ~2019 JavaScript, onto modern web primitives”), r/webdev and among accessibility experts. Two themes dominate.
1. “Chrome-only APIs in a neutral wrapper.” The loudest complaint, as summarized by the DEV write-up: a Hacker News commenter listed about 40 features the guides mention that ship in Chrome but not Firefox or Safari — CSS @function, interpolate-size, corner-shape, the Prompt API, fetchLater() and beforeinstallprompt. On r/webdev, one user called it a way to “sneak in non-standard Google-only APIs.” The team’s reply: the default target is Baseline Widely available, single-engine features sit behind the volatile-features opt-in, guides document fallbacks, and Firefox and Edge now hold owner seats. That is a fair defence. It is also fair to note that WebKit has no seat, and the dev.to piece points out that beforeinstallprompt is a Blink API other engines declined.
2. Accessibility doesn’t follow automatically. Accessibility consultant Adrian Roselli tested the May preview with Google’s own showcased prompt — “Create an accordion-style stats component that smoothly animates on open and close” — in Antigravity. He reported the animation did not work in Firefox and that he found WCAG failures “within moments.” His core point is structural: LLMs are non-deterministic, so no guide is guaranteed to be picked up or read in full, and he quotes a maintainer conceding exactly that. That was the preview; 1.0 added an accordion guide and accessibility review, but the underlying limit hasn’t changed.
Honest Limitations
- Activation is probabilistic. The skill says “MANDATORY,” but the agent decides. note inc.’s data shows explicitly naming MWG in prompts lifts results further. For important UI work, say “use modern-web-guidance” in the prompt.
- More tokens and more time. SEJ observed guided runs were slower and used more tokens in most suites. Guides list their
tokenCount; a dialog-heavy task can pull several thousand tokens of guidance. legacy-scanis narrow. About 20% of guides have deterministic legacy rules. It will not find most modernization opportunities in a real codebase.- Accessibility checks are automated and partial. The dashboard says so itself. You still need manual and assistive-technology testing.
- The evidence is mostly first-party. The benchmark is open source and re-runnable, but every published number so far comes from Google or partners it chose to feature.
- Chrome-flavoured edges. Built-in AI guides target Chrome’s on-device models; volatile and origin-trial guides are often Blink-first.
- Node 22+ can bite older CI images.
Modern Web Guidance vs. Alternatives
| Option | What it is | Strength | Weakness |
|---|---|---|---|
| Modern Web Guidance | Curated, eval-backed guides + offline search CLI | Browser-engineer authorship, Baseline-aware, public A/B evals | Agent may not use it; first-party evidence |
Hand-written AGENTS.md / Cursor rules | Your own “prefer <dialog>” rules | Fully tailored, zero overhead | You must know and maintain the modern patterns yourself |
| Context7-style live docs MCPs | Fetches library docs on demand | Great for framework/library APIs | Not curated for platform best practices or accessibility |
| Chrome DevTools MCP | Runtime inspection, traces, screenshots | Verifies what actually renders | Doesn’t tell the agent what to write |
| Linters (stylelint, eslint-plugin-compat, axe) | Static/rule-based checks | Deterministic, CI-friendly | Catch symptoms, not the better native alternative |
Google recommends MWG for authoring plus Chrome DevTools MCP for verification: one tells the agent what good looks like, the other checks whether it happened.
Who Should Use It
- Teams shipping UI with Claude Code, Codex, Cursor or Copilot: install it; the cost is a few thousand tokens per frontend task.
- Teams with a PR review bot: copy MetaMask’s reviewer setup, the best-documented win so far.
- Not a fit if you need guaranteed WCAG conformance or strict Safari parity without manual checks.
FAQ
What is Modern Web Guidance?
Modern Web Guidance is an Apache-2.0 agent skill and offline CLI from Google Chrome, now co-stewarded with Microsoft Edge, Mozilla Firefox and MDN. It gives AI coding agents about 200 expert-written guides on modern HTML, CSS and JavaScript, with Baseline browser-compatibility data, so they stop defaulting to legacy patterns.
Is Modern Web Guidance free, and does it send my code anywhere?
It is free and open source under Apache-2.0, with no account or API key. Search runs locally on an embedding model plus BM25; guides ship inside the npm package. Your agent’s own model provider still sees whatever the agent sends it.
Which coding agents does it work with?
Any agent that supports skills. Official install paths exist for Claude Code, Codex, Cursor, GitHub Copilot CLI, Gemini CLI, Antigravity, JetBrains WebStorm, Goose, Grok and Kimi Code, plus gh skill install and npx skills add.
Will it make my site use Chrome-only features?
Not by default. It targets Baseline Widely available unless you set a different Baseline target in AGENTS.md or CLAUDE.md. Single-engine “volatile” features and origin-trial features require explicit opt-in commands. Critics still argue some guides lean Chromium-first, so review what you enable.
Does it guarantee accessible code?
No. Guides got accessibility expert review for 1.0, and Google’s automated checks show large gains, but those checks are not a WCAG audit, and the project concedes agents may not pick up or fully read a guide. Keep manual and assistive-technology testing.
Sources
- GoogleChrome/modern-web-guidance — distribution repository
- GoogleChrome/modern-web-guidance-src — source, evals and graders
- Release v1.0.0 notes
- Release v1.0.1 notes
- Modern Web Guidance 1.0 launch post — Chrome for Developers
- Get started with Modern Web Guidance — official docs
- Modern Web Guidance eval dashboard
- GOVERNANCE.md
- Search Engine Journal — Google Releases Modern Web Guidance 1.0
- Adrian Roselli — Maybe Don’t Rely on Google’s “Modern Web Guidance”
- DEV Community — Chrome’s Fix for Agents That Still Write 2019 Web Code