On November 10, Chrome shipped Modern Web Guidance 1.0, and the project is now stewarded by Chrome, Edge, Firefox, and MDN together. On X it got passed around as "the thing that fixes AI coding habits", usually right next to the other running complaint of the week: vibe-coded sites all look the same, and they all ship the same 2019-era front-end code underneath.
The pitch is simple. Coding agents can make almost anything work with JavaScript, but a web platform expert reviewing that code can usually find a native HTML or CSS feature that does the job with less code, better accessibility, and better performance. Modern Web Guidance packages that expertise as skills your agent can search, plus a static scanner called legacy-scan. The project's own release notes report big pass-rate jumps on their evals when agents use the guidance. Those are their numbers, measured on their task set, so treat them as a reason to try it, not as a promise.
I wanted to know something narrower: if you just vibe-coded a marketing site, what does this actually catch before launch, and what does it not? So I ran it.
The test: one AI-style landing page
I didn't scan a customer's site. I wrote a small fixture, acme-landing, in the style that agents and app builders produce for a typical SaaS landing page: a React component file, a static HTML entry, and two stylesheets. It has the usual suspects:
- a "Book a demo" modal built from a
<div role="dialog">, with a hand-rolledEscapelistener andbody.style.overflow = "hidden" - a sign-up form with
type="text"for email and a bare password field - a testimonial rendered with
dangerouslySetInnerHTML - a fade-in wrapper built on
IntersectionObserver - a dark-mode toggle that writes to
localStorageand flips a.darkclass - a nav that highlights the current section from a
scrolllistener - a hover-only tooltip
-
::-webkit-scrollbarstyling and a-webkit-mask-imagefade - a third-party script and stylesheet from a CDN
None of this is broken. It renders, it passes a quick click-through, and it is exactly what ships when the only test is "does it look right in my browser".
Step 1: run the scanner
You need Node 22 or newer. From the project root:
npx modern-web-guidance@latest legacy-scan . One gotcha first: my very first run returned 0 findings, because I'd named the folder demo-site. The scanner skips docs, examples, demos, and tests by default. If your project lives in a folder with "demo" or "example" in the path, add --include-docs-and-tests or you'll get a clean bill of health you didn't earn.
After renaming the folder, here is the real output:
Six findings across five guides:
| Guide | What it flagged | The fix |
|---|---|---|
autofill-sign-up-form | Password input with no autocomplete | autocomplete="new-password" on sign-up forms |
complex-shapes, soft-edge-content-fade | -webkit-mask-image with no standard property | Add unprefixed mask-image |
customize-scrollbar-color-and-thickness | ::-webkit-scrollbar rules | scrollbar-color and scrollbar-width |
dark-mode-toggle | localStorage + .dark class toggle | Update <meta name="color-scheme">, use CSS color-scheme and light-dark() |
Every finding comes with Keep when / Drop when criteria, and the tool says plainly that static results are provisional. That's the right design. A scanner that tells your agent to "fix" everything it matches would churn code for no reason. A scanner that tells it when the finding doesn't apply gives it a way to say no.
Step 2: notice what it didn't flag
This is the part the launch threads skipped. The header of the output says it outright: legacy-scan has deterministic rules for 38 guides, about 20% of the corpus. On my fixture, the biggest problems weren't in that 20%:
The div modal, the unsanitized HTML, the scroll-listener nav, the IntersectionObserver fade, the hover-only tooltip, and the type="text" email field all passed the scan. Those are the ones that hurt real users: keyboard and screen-reader users get trapped in or lost behind the fake modal, the testimonial is an XSS path the day someone wires it to a CMS, and the email field doesn't get the right mobile keyboard or autofill.
The scanner isn't wrong. It just isn't the whole tool. The other 80% is reached through search and retrieve, which is how the skill is meant to be used by an agent:
npx modern-web-guidance@latest search "modal dialog with form" # -> dialog, declarative-dialog-popover-control, prevent-page-scroll-under-modal-dialog, ... npx modern-web-guidance@latest search "render user-provided html safely" # -> sanitize-untrusted-html, security, ... npx modern-web-guidance@latest search "highlight nav link for section in view" # -> scrollspy, navbar, ... npx modern-web-guidance@latest search "fade in element when it scrolls into view" # -> scroll-entry-exit-effects, ... npx modern-web-guidance@latest retrieve dialog The dialog guide is a good example of why this is worth wiring in. It's opinionated in exactly the places models get it wrong. Use a native <dialog> opened with showModal() or the declarative command="show-modal" button. Don't add role="dialog", aria-modal, a focus trap, or an Esc handler, because the native modal already gives you an inert page, focus containment, the top layer, ::backdrop, Esc dismissal, and focus return. And don't lock scrolling with overflow: hidden on body. Use overscroll-behavior: contain on the dialog and backdrop instead. My fixture did every one of those "don'ts".
Step 3: make it part of how the agent works, not a one-off
Running the scan once before launch is fine. Making the agent use it every time is better. The install command adds the skill to your coding agent's setup:
npx modern-web-guidance@latest install Then I'd add three lines to whatever rules file your agent reads (AGENTS.md, .cursorrules, CLAUDE.md):
- Before building any overlay, form, scroll effect, tooltip, theme toggle, or HTML-rendering component, run `modern-web-guidance search` for it and follow the retrieved guide. - Before marking a UI task done, run `legacy-scan --json` on changed files. Apply findings only when the guide's "Keep when" criteria match. Say which ones you dropped and why. - Never add role="dialog", aria-modal, or a manual focus trap to a native <dialog>. The 1.0 skill describes the same loop for modernization: scan, verify, report, modernize. The "verify" step is where you stay in charge.
For CI, legacy-scan --json gives you structured output. I wouldn't fail the build on it yet, since a fifth of the corpus is covered and the results are provisional by design. Post it as a PR comment and let a human decide.
Why a marketing site, specifically, should care
It's tempting to file this under "app engineering" and skip it for a landing page. I'd argue the opposite. A marketing site is the page a stranger, a search crawler, and an AI answer engine all see first, and they all reward the same things native features give you:
- Less JavaScript before content. Native
<dialog>, popovers, and CSS scroll-driven effects replace a pile of listeners and state. That means a lighter page and fewer layout-shift surprises. - Content that exists in the HTML. There's a guide called
search-hidden-contentfor accordions, tabs, and "read more" sections that stay findable with Find in page, indexable, and deep-linkable. If your FAQ answers only appear after a click handler runs, crawlers and answer engines may not treat them as part of the page. That matters if you want your pages to be the kind of source AI engines quote. - Forms that convert on mobile. Correct
typeandautocompletevalues are boring and directly tied to sign-ups.
Where this leaves your builder
Whether you vibe-code the site in Cursor or Claude Code, or generate it with an AI website builder, the useful question has shifted. "Can it produce a page?" is settled. "Does it produce the page a platform expert would sign off on?" is the new bar. That's a fair test to run on any tool before you commit: generate a page with a modal, a form, an FAQ, and a theme toggle, then run legacy-scan and the four searches above on the output. If you're comparing options, add it to your list of what to check when evaluating an AI website builder, next to the SEO basics in this comparison of website builders for SEO.
The ten-minute pre-launch version
# 1. Scan (include demo/example folders if your app lives in one) npx modern-web-guidance@latest legacy-scan . --include-docs-and-tests # 2. Search for the things the scanner can't see yet for q in "modal dialog" "sanitize untrusted html" "scrollspy" \ "scroll reveal animation" "tooltip" "sign up form autofill"; do npx modern-web-guidance@latest search "$q" done # 3. Retrieve and apply only what matches your code npx modern-web-guidance@latest retrieve dialog,sanitize-untrusted-html Then read the diff your agent produces. The guidance is good. It's still a guide, not a reviewer.
What did legacy-scan find on your site? I'm curious whether the "missed" column looks the same on real projects as it did on my fixture.



![Motion Planning and Navigation — Ch.11: Legged Robot Navigation [KR]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqftgs44jxvhe8fxlcrvt.png)