Skip to main content

Modern Web Guidance 1.0: Web Platform Skills for Coding Agents, and Where They Fit Our Stack

· 11 min read
Gergely Sipos
Gergely Sipos
Frontend Architect

The Chrome team shipped Modern Web Guidance 1.0 on November 10, 2026, and a day later published the top 10 things AI gets wrong in web development. We first mentioned the project in our Google I/O recap when it was an early preview. With the stable release, it is worth a closer look.

This post covers what Modern Web Guidance (MWG) is, how it works, what it fixes, and how it fits our recommended tech stack. Short version: the guidance is good and mostly matches what we want. But two parts need care: our component libraries already handle some of the things MWG wants to rewrite, and the default install command breaks our supply-chain rules.

What it is​

Modern Web Guidance is a set of agent skills with web platform knowledge in them. It is not a framework or a linter. It is a package of guides that a coding agent (Claude Code, Copilot, Cursor, Codex and others) loads while it writes or reviews code.

Each guide targets a "knowledge gap": a place where models still write outdated or wrong code even though a better platform feature exists. The guides have Baseline and browser compatibility data built in, so the agent can choose a feature that matches the project's browser support.

Some facts about the project:

How it works​

You install the skill into a project, and from then on your agent can use it.

npx modern-web-guidance@latest install
npx modern-web-guidance@latest update

It is also in the plugin marketplaces of Claude Code, Codex, Cursor, Antigravity, Copilot, WebStorm, Kimi Code and Grok Build. (Before you run either of these, read the supply-chain section below.)

After it is installed, the agent uses it in three ways:

  1. Passively, while it writes code. When a task touches a covered area, such as a modal, a form or dark mode, the agent loads the matching guide and follows it instead of using the patterns from its training data.
  2. Explicitly, with a slash command. You can call the skill directly, for example /modern-web-guidance Modernize the code in this directory.
  3. As a modernization workflow. This is new in 1.0. The skill uses static analysis to scan HTML, CSS, JS and package.json for safe upgrade opportunities. The 1.0 version only looks for a deliberately narrow set of patterns, so the results are predictable. "Agentic audits", where the agent reasons about the code itself, are planned for later.

The guides cover four areas:

AreaExamples
Accessibilityfocus and inert, reduced motion, accessible form validation
User experienceswipe and touch, dialog and popover transitions, light/dark themes
Performancemain-thread scheduling, offscreen rendering, layout shift prevention
SecurityHTML sanitization, strict CSP, passkeys

MWG gives the agent guidance before it writes code. It cannot check what happens at runtime. For that, Chrome recommends using it together with Chrome DevTools for agents. With DevTools, the agent can profile on a throttled CPU until main-thread tasks are under 50 ms, record animations to check them, confirm prefers-reduced-motion behavior, and look for memory leaks in cached SPA views.

Does it actually help?​

Chrome tests every guide with evals. Each guide defines a set of expectations. The same prompt runs once with MWG installed and once without, and both outputs are checked. The public dashboard showed about 52% of checks passing without MWG and 91% with it (as of November 9, 2026). The article text rounds these to "about 50%" and "around 90%".

The release post also has partner case studies. These numbers come from the partners and the vendor, so treat them as examples, not benchmarks:

  • note inc.: in 180 runs on a production Next.js codebase, the pass rate on modern web checks went from 61% to 94%.
  • MetaMask: MWG runs as a PR review bot on their browser extension. In five weeks it reviewed about 480 PRs, commented on 64, and 43 of its findings were fixed.
  • WeTV and Policybazaar: both report large time savings in performance debugging and audits when MWG is combined with DevTools for agents.

One security detail stood out: across the whole eval suite, models never added a CSP or cross-origin isolation headers unless the prompt asked for them.

The top 10 gaps​

The companion article lists the ten most common mistakes from the evals. In short:

#AreaWhat agents get wrongWhat MWG recommends
1Focus and inertJS focus traps, focus not moved to new views or restored when the user returns, every toolbar item is a tab stopmodal <dialog>, inert on background content, roving tabindex
2Reduced motionmotion not gated, blanket * { transition: 0.01ms } resetsgate specific motion (including @view-transition) behind prefers-reduced-motion, keep non-motion state transitions
3Formscustom blur validation, aria-invalid out of sync with the visible error, placeholders used as hints:user-invalid, aria-invalid kept in sync, hints above the input linked with aria-describedby
4Swipe and touchpointermove physics, accidental back/forward swipesCSS Scroll Snap, overscroll-behavior-x: none, scroll-driven animations
5Dialogs and popoverscustom overlays, setTimeout enter/exit state machines, overflow: hidden scroll lockspopover, <dialog>, @starting-style + transition-behavior
6Dark modewhite flash on load, a binary toggle with no way back to the OS setting, no sync between tabs<meta name="color-scheme">, light-dark(), a "system" option, the storage event
7Runtime responsivenesshome-made setTimeout queues, dense grids rendered in fullscheduler.postTask() / scheduler.yield(), content-visibility: auto
8Layout shift<video> without dimensions, font swaps, static vh, anti-flicker snippetsaspect-ratio, font-size-adjust, dvh/svh, blocking="render"
9XSShand-written sanitizers, DOMPurify always bundled, passthrough Trusted Types policiesnative setHTML(), DOMPurify lazy-loaded as a fallback, hash- or 'strict-dynamic'-based CSP
10Passkeyshand-written base64url helpers, no capability checksparseCreationOptionsFromJSON(), getClientCapabilities(), signalUnknownCredential()

Most of these mistakes are not unusual. They are the code that was correct five years ago and is still everywhere in the training data. That is the real problem MWG solves: models know the old way better than the new one.

How it fits our stack​

Where it fits well​

  • Agents we already use. Claude Code and Copilot both use the open Agent Skills format, and MWG is a normal skill. It needs no new tooling, and it sits next to our existing CLAUDE.md and Copilot instruction files.
  • Tailwind and shadcn/ui theming (gap 6). shadcn/ui switches themes with a .dark class. What agents usually forget are the parts around it: <meta name="color-scheme" content="light dark">, color-scheme on the root element so native controls and scrollbars match the theme, and a "system" option in the theme toggle. MWG adds these without fighting Tailwind.
  • Performance and layout shift (gaps 7 and 8). These are plain CSS and platform APIs. They fit any React app, and they matter most in the data-heavy dashboards we often build: long tables, chart grids, and SPA views kept alive between routes.
  • Security headers (gap 9). Our projects deploy to Firebase Hosting, where headers are set in firebase.json. An agent that suggests a strict CSP when nobody asked for one is an improvement. Our Web Security Essentials page already asks for this.
  • Passkeys (gap 10). We rarely build passkey flows by hand because Firebase Auth handles most sign-in. When we do, the native JSON helpers are clearly better than hand-written base64url code.

Where it needs care​

  • Component libraries own dialogs, popovers and focus (gaps 1 and 5). Our default UI is shadcn/ui on Base UI or Radix. These libraries implement their own dialog, popover, focus trap and scroll lock, and they are tested for accessibility. An agent in "modernize" mode could see a JS focus trap and try to replace it with a native <dialog> inside a component we do not maintain. The rule: if a library component exists for it, use the library. Apply MWG's dialog and popover advice to custom one-off overlays only, and tell the agent this in your project instructions.
  • Form validation (gap 3). Our complex forms use React Hook Form with Zod, and RHF controls when errors appear. :user-invalid styling may not match RHF's error state, so do not mix the two. The other advice still applies: keep aria-invalid in sync with the visible error, show persistent hints above the input, and link them with aria-describedby.
  • DOMPurify (gap 9). Our DOMPurify page recommends DOMPurify.sanitize() before dangerouslySetInnerHTML. MWG prefers the native Sanitizer API (setHTML()) and loads DOMPurify only as a fallback. The two do not conflict: DOMPurify is still the right fallback, and we should look at lazy-loading it. Because setHTML() writes directly into a DOM element, it does not work with dangerouslySetInnerHTML. In React it needs a ref. Expect agents to propose this change, and review it.
  • Browser support targets. MWG's Baseline-aware advice is only as good as the support target it can find. Many of our projects never write one down. Add the browser support target to AGENTS.md / CLAUDE.md (and to Vite's build.target if it differs from the default), so the agent does not pick features your users' browsers do not have.

Supply chain: don't run @latest​

The documented install command is npx modern-web-guidance@latest install. This goes against two of our rules:

  1. No mutable tags. We pin exact versions. Use npx modern-web-guidance@1.0.0 install and commit the installed skill files to the repo, so every teammate and CI agent uses the same guidance and updates show up in a reviewable diff.
  2. The 7-day release age. Version 1.0.0 was published on November 10, 2026. If your .npmrc sets min-release-age=7, npm will not resolve it before November 17. Wait. Do not override the gate.

Also remember that the package contains an executable script (modern-web.mjs) that your agent will run. It is a well-known publisher and the source is open, but follow our usual agent security habits: read the skill before you install it, and review its diff before you accept an update.

Our take​

Modern Web Guidance answers a real problem we see in agent-written frontend code: it works, but it is often outdated, a bit inaccessible, and has no security headers. The guides come from browser vendors, are reviewed by experts, have Baseline data built in, and have public evals. That is better than anything we would write ourselves.

Our recommendation:

  • Try it on one active project using Claude Code or Copilot. Install a pinned version, commit the skill, and say in the project instructions that UI primitives come from the component library.
  • Use the modernization workflow as a reviewer, not as an autopilot. Run it on a branch, read the suggested changes, and drop anything that rewrites library components.
  • Combine it with DevTools for agents when performance or animation is part of the task.
  • Check back after a few weeks with a short report. If it works well, it should get a page in the AI section and a line in our default project setup.

Sources​