AI learned to build websites from years of old code. So when you ask for a smooth accordion or a tooltip, it writes 60 lines of JavaScript for something the browser now does in one line of CSS. Modern Web Guidance is a free skill pack, stewarded by the Chrome, Edge, Firefox and MDN teams, that gives your agent the modern answer before it writes.
Install is one command. Making your agent use it is the guide.
The repo itself says a guide may not get used, because agents are not deterministic. So this page is about the three things that decide whether it changes your code: a rule that forces it, a prompt that fixes your old code, and a cheat sheet so you can spot when the agent skipped it.
// Build this with your AI agent
Build this with your AI agent
Want to try this? Copy the setup prompt into your coding agent with this guide's link. It installs the pack, adds the rule, scans your site and reports. It fixes nothing until you say yes.
Read this guide: https://codewithnishant.dev/free/modern-web-guidance-agent-rules/ and the Modern Web Guidance README it links to (https://github.com/GoogleChrome/modern-web-guidance). Help me make you write modern web code in this project: 1. Install Modern Web Guidance for the agent I am using, with the route the README gives for it. For Claude Code, use the GitHub marketplace command, not the built-in plugin directory. Ask me first if I want telemetry off (DISABLE_TELEMETRY=1). 2. Add the "Web UI rule" block from section 02 of the guide to my AGENTS.md or CLAUDE.md. Do not overwrite anything there. If any of my lines contradict it, show me and ask. 3. Run: npx -y modern-web-guidance@latest legacy-scan . --json 4. Check every finding against its keepWhen and dropWhen rules. Drop false positives such as vendor code, fallbacks and copied design files. 5. Show me the verified list in plain words: file, line, what is old, what the guide says to use. Do not change any code yet. Ask before anything paid or anything that publishes.
01. What it is in 60 seconds
The short answer: a local library of modern web guides. Your agent runs search, a small model on your machine picks the best guide (no network, no keys), then retrieve drops that one guide into the agent's context.
- Size: 250 modern web features and 203 real use cases, across user experience, CSS layout, performance, forms, accessibility and built-in AI (README).
- Who: stewarded by Google Chrome, Microsoft Edge, Mozilla Firefox and MDN. Version 1.0.0 shipped on 10 November 2026 (Chrome blog).
- Two repos, do not mix them up:
modern-web-guidanceis the pack you install (13,776 stars on 14 November).modern-web-guidance-srcis the source and the issue tracker.
Here is what my agent got back when I searched for a dialog animation. Real output, trimmed to the top 4 of 10:
animate-to-from-top-layer Animate elements such as dialogs, popovers, and tooltips
as they're entering/exiting the top layer.
light-dismiss-a-dialog Create a modal dialog that can be closed via light dismiss
prevent-page-scroll-under-modal-dialog
Prevent the underlying page from scrolling while a modal
dialog is open.
dialog Build a modal or non-modal dialog component that is
accessible, manages focus appropriately ...Then retrieve animate-to-from-top-layer returned a guide of about 1,360 words: the steps, a full CSS example and reduced motion handling. So a retrieved guide costs a few thousand tokens, not the 205 tokens of the skill file.
02. The rule that makes your agent use it
The short answer: paste this block into your AGENTS.md or CLAUDE.md. It tells the agent to search before any web UI work, and to prove it at the end of the reply.
## Web UI rule (Modern Web Guidance)
- Before writing or changing any HTML, CSS or browser JavaScript, run
`npx -y modern-web-guidance@latest search "<2-5 word task>"` and retrieve the best match.
Do this even for small changes. Skip it for backend, build config and tests.
- Follow the retrieved guide, including its fallbacks. Do not add a library
for something the guide does natively.
- Browser support: features that are Baseline Widely available are fine.
For anything newer, keep the guide's fallback.
- End every reply that changed web UI with a `### Modern Web Guidance` section
listing each guide ID you used. If you used none, say which you searched and why none fit.
- Never run `legacy-scan` unless I ask for a scan.Why each line is there
- Search first, even for small changes: the skill's own description already says "MANDATORY: Execute FIRST" for HTML, CSS and browser JS. Agents still skip it. Your project file is read every session, so it is a second, louder reminder.
- Follow the fallbacks: most guides I pulled mark their feature as limited availability. The guide's fallback is what keeps older browsers working.
- Browser support line: the skill's SKILL.md itself suggests writing a browser policy into AGENTS.md or CLAUDE.md. Change it if you need older browsers.
- The receipt section: SKILL.md already asks the agent to end with a
### Modern Web Guidancesection naming each guide and quoting the rule it followed. Making it required means you can see at a glance if the guide was used. - No surprise scans: SKILL.md says the scan is only for open-ended modernization. This line keeps it that way.
How to know it worked
- Ask for something small, like "add a tooltip to the save button".
- Look at the end of the reply. A
### Modern Web Guidancesection with a guide ID likeinterest-triggered-tooltipsmeans it searched and used it. - No section? It skipped the guide. Ask "did you search Modern Web Guidance?" and let it redo the change.
One tip: read the skill's SKILL.md once, and delete any line of yours that says the opposite. Two rule files that disagree make the agent guess.
03. Modernize an old site
The short answer: run legacy-scan, check each finding, then fix one at a time. Here is the prompt, then what it found on my own site.
Modernize the web code in this project with Modern Web Guidance, one finding at a time.
1. Run: npx -y modern-web-guidance@latest legacy-scan . --json
2. Check each finding against its keepWhen and dropWhen rules. Drop false positives.
3. Show me the verified list first. Wait for my OK.
4. Then for each finding, in order: retrieve its guide, apply the fix with the guide's
fallback, show me the diff, and wait for my OK before the next one.
5. Stop and ask if a fix touches more than one file.
6. When done, run legacy-scan again and tell me what is left and why.What it found on my site
I ran it on a copy of my portfolio, not the live site. The tool said: "Found 8 modernization opportunities across 5 guides", from about 20% of its guides, and called the results provisional. Nothing below is fixed yet. The last column is my own read using the tool's keep and drop rules.
Found 8 modernization opportunities across 5 guides (scanned 33 guides with deterministic rules; ~20% of the guidance corpus) * animate-to-intrinsic-sizes (1) src/home/home.css:190 * checkbox (1) src/site/pages.css:229 * custom-text-decorations (3) src/library.css:678 and 2 more * dark-mode-toggle (2) src/site/chrome.js:140 and 1 more * ime-safe-enter-submit (1) src/site/enquiry.js:98
| Finding | Plain meaning | What the guide says | My read |
|---|---|---|---|
Fake height animation, home.css:190 | Animates max-height from 0 to fake an "open" effect | interpolate-size: allow-keywords, animate the real height, keep max-height as a fallback | Keep. Small but real |
Custom checkbox, pages.css:229 | The real checkbox is hidden and a box is drawn on a span | accent-color, or appearance: none on the input itself | Keep. Gets native keyboard and focus back |
| Underline hack, 3 places | border-bottom used as an underline | text-decoration plus text-underline-offset | Keep 2. The third is a copied design file, not the live site |
| Dark mode toggle, 2 places | The toggle changes a class but not <meta name="color-scheme"> | Update the meta, and use color-scheme with light-dark() | Keep 1. The other is the same copied design file |
Enter key, enquiry.js:98 | Enter can submit while someone is still typing in Hindi, Japanese or Chinese | Check event.isComposing, plus keyCode === 229 for older Safari | Keep. The one real bug class here |
So 8 findings became 6 real ones after the check. That check is step 2 of the prompt, and it is why the prompt shows you the list before touching anything.
After each fix, check it yourself
- Use it with only the keyboard: Tab, Enter, Space, Esc.
- Open it in Firefox and Safari, not just Chrome.
- Turn on reduced motion in your system settings and check the animation calms down.
- Run a quick screen reader pass (VoiceOver on Mac, NVDA on Windows).
- Run
legacy-scanagain on the changed files.
Why bother: accessibility expert Adrian Roselli tested the early preview and found accessibility errors in its output within moments, plus an animation that failed in Firefox. That was before 1.0, but the lesson holds: a guide helps, it does not replace a check.
04. Old vs new cheat sheet
The short answer: 12 things AI still writes the old way, the native replacement, and the guide ID to ask your agent for. Most of these features are marked limited availability in the guides, so use them with the guide's fallback.
| What AI still writes | Native replacement | Guide ID |
|---|---|---|
max-height trick for expand and collapse | interpolate-size: allow-keywords | animate-to-intrinsic-sizes |
| JavaScript accordion | <details name="group"> | accordion |
| Hidden checkbox plus a painted span | accent-color | checkbox |
| JavaScript toggle switch | <input type="checkbox" switch> | switch |
border-bottom as an underline | text-underline-offset | custom-text-decorations |
| Dark mode by class only | <meta name="color-scheme"> plus light-dark() | dark-mode, dark-mode-toggle |
| Enter key submits a form | Check isComposing and keyCode 229 | ime-safe-enter-submit |
| JavaScript fade for a modal | @starting-style, transition-behavior: allow-discrete, overlay | animate-to-from-top-layer |
| Click outside to close, in JavaScript | <dialog closedby="any"> | light-dismiss-a-dialog |
body { overflow: hidden } scroll lock | overscroll-behavior: contain on the dialog | prevent-page-scroll-under-modal-dialog |
| A tooltip library | popover="hint" plus interestfor | interest-triggered-tooltips |
onclick to open a popover | commandfor plus command | declarative-dialog-popover-control |
Four of them in code, short on purpose, adapted from the guides:
Expand and collapse without max-height
:root { interpolate-size: allow-keywords; }
.panel { block-size: 0; overflow: hidden; transition: block-size .4s ease-out; }
.panel.open { block-size: auto; }Browsers without support jump straight to the open size. Nothing breaks.
Enter to submit, safe for Hindi and Japanese keyboards
input.addEventListener('keydown', (event) => {
if (event.key === 'Enter') {
event.preventDefault();
if (event.isComposing || event.keyCode === 229) return;
form.requestSubmit();
}
});A tooltip with no library
<button interestfor="tip">Save</button>
<div popover="hint" id="tip">Saves a draft, nothing is published</div>A real underline with space under it
:where(a) {
text-decoration: underline solid currentColor max(1px, 0.08em);
text-underline-offset: 0.2em;
}Code adapted from the Modern Web Guidance guides by the Chrome, Edge, Firefox and MDN teams, licensed CC-BY 4.0. I shortened the snippets. The full guides add fallbacks, reduced motion and accessibility notes, so ask your agent to retrieve the guide rather than copy these.
05. Honest settings and costs
The short answer: turn telemetry off if you care, leave experimental features locked, and expect more tokens per task.
| Setting or cost | What to know | Source |
|---|---|---|
| Telemetry | On by default. Sends install counts, the agent's name, guide IDs and your agent's search queries. Not your code or your prompts. Turn it off with export DISABLE_TELEMETRY=1 in .zshrc or .bashrc. | README |
.mwgrc | Origin Trial and volatile features show up in search but are locked on retrieve. Unlock per project with "allowOriginTrials": true or "allowVolatileFeatures": true in a .mwgrc file (or ~/.mwgrc). Leave them off unless you know why you need them. | README |
| Browser target | Guides assume Baseline Widely available is safe without fallbacks. Anything newer gets the guide's fallback, unless you write your own policy. | SKILL.md |
| Token cost | Guided runs used about 16% to 43% more uncached tokens for Claude Code and Antigravity in October nightlies, and more for Codex, which the team says is partly how it is measured. | Issue 3138 |
| Claude Code install | The built-in plugin directory served an old version. Install from the GitHub marketplace instead (section 06). | Issue 3533 |
| Scan limits | Checks about 20% of the guides. Stops at 5,000 files with no warning, so big repos are under-scanned. Skips docs and tests unless you add --include-docs-and-tests. | Issue 3596 |
06. Install routes
The short answer: one wizard for everything, or your agent's own plugin command.
# Any agent, interactive wizard
npx modern-web-guidance@latest install
# Claude Code (GitHub marketplace, not the built-in directory)
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/reload-plugins
# Codex
codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome
# GitHub CLI skills
gh skill install GoogleChrome/modern-web-guidance
# Update later (if you used the wizard)
npx modern-web-guidance@latest updateAntigravity, GitHub Copilot CLI, Grok and Kimi have their own one-liners in the README's install section. To try it without installing, run npx modern-web-guidance@latest legacy-scan . in a project folder.
07. Their numbers, labelled
On the makers' eval dashboard on 13 November 2026, the best-practice pass rate went from 52% without the guides to 92% with them, across 1,104 tasks and 3 agents. These are their own self-reported tests, on their own tasks, graded by their own automated checks in a real browser. The dashboard updates nightly and says it is not a full accessibility audit. Treat it as a reason to try it, not as proof for your project.
FAQ
Is Modern Web Guidance free?
Yes. The code is open source under Apache-2.0 and the guides are CC-BY 4.0. It runs offline with no API keys. What costs money is your coding agent's tokens, and guided runs use more of them.
Does it work with Claude Code, Codex and Cursor?
Yes for Claude Code and Codex, which have their own plugin commands in the README, as do Antigravity, GitHub Copilot CLI, Grok and Kimi. For other agents, like Cursor, start with the general npx install command, which the README calls an interactive wizard. In Claude Code, install it from the GitHub marketplace, not the built-in plugin directory.
Does it cost more tokens?
Yes. In Chrome's own October nightly runs (GitHub issue 3138), guided runs used about 16% to 43% more uncached tokens for Claude Code and Antigravity, and more for Codex, which the team says is partly a measurement issue. Each retrieved guide is a few thousand tokens.
Does it send my code to Google?
Not your code or your prompts. By default it sends anonymous usage data: install counts, the agent's name, the guide IDs it retrieves and the search queries your agent writes. Set DISABLE_TELEMETRY=1 in your shell profile to turn that off.
Will my agent always use it?
No. AI agents are not deterministic, so nothing guarantees a guide is searched or followed. A rule in AGENTS.md or CLAUDE.md makes it far more likely, and asking for a Modern Web Guidance section at the end of each reply lets you see whether it happened.
Does legacy-scan find every old pattern?
No. It checks a curated subset, about 20% of the guides, with fixed rules. It stops at 5,000 files, skips docs and tests unless you ask, and calls its own results provisional, so each finding needs a quick check.
Is the 52% to 92% result real?
It is the makers' own number, from their own 1,104 tasks and their own automated graders, shown on their eval dashboard on 13 November 2026. It is not an independent test, and the dashboard says it is not a full accessibility audit.
What I checked, and what I did not
On 14 November 2026 I ran three commands myself: search, retrieve, and legacy-scan on a copy of my own portfolio. I read the README, the skill's SKILL.md, 19 guides from the repo, issues 3138, 3501, 3533, 3552 and 3596, the 1.0 announcement, the eval dashboard and Adrian Roselli's post. GitHub showed 13,776 stars and the Apache-2.0 licence that day.
I did not install it into my daily agent, I did not test the rule above in a real agent session, I did not fix my 8 findings yet, and I did not run their evals. The rule and the prompts follow the skill's own instructions, so read what your agent does before you approve it.
More on working with coding agents: a CLAUDE.md template (where the rule goes), when your agent writes too much code, 8 files before you vibe code and the vibe coding safety checklist.
Your AI is not bad at websites. It is just reading from 2019. Give it the new book, then check that it opened it.
// Free newsletter
I send out guides like this every week
Real setups, real sources, no hype. Drop your email and I'll send you the next one.