# Modern Web Guidance

_How Chrome, Edge, Firefox and MDN are teaching AI coding agents to write modern web code, explained in short animations._

> An animated guide to Modern Web Guidance 1.0: the skills and CLI that steer AI coding agents from legacy web patterns to modern platform APIs, what it changes, how it was tested and how to install it.

- URL: https://www.insidethebox.dev/guides/modern-web-guidance
- Published: 2026-11-19

## What changes (legacy → modern)

- **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

## Safe for every browser

- **Progressive enhancement:** Purely additive features are ignored by older browsers; critical behaviour gets a fallback.
- **Responsible fallbacks:** Small custom fallbacks (under 50 lines) or polyfills loaded only when needed.
- **Baseline-aware:** Uses live compatibility data from the Baseline project.
- **Gated experiments:** Origin-trial and very new features stay off until you opt in.

## Coverage: 262 features, 204 use cases

- Accessibility (e.g. accessible-error-announcement, respect-os-text-scale)
- Built-in AI (e.g. summarizer, translator, language-detection)
- CSS (e.g. css-layout, responsive-design, fluid-scaling)
- Forms (e.g. autofill-sign-in-form, validate-input-after-interaction, switch)
- HTML (e.g. custom-elements, shadow-dom, web-components)
- JavaScript (e.g. sort-high-precision-timestamps, calculate-event-differentials)
- Performance (e.g. break-up-long-tasks, identify-inp-causes, optimize-image-priority)
- Privacy (e.g. privacy)
- PWA (e.g. install-web-app, migrate-web-app-origin)
- Security (e.g. passkeys, sanitize-untrusted-html, trusted-types)
- UI atoms (e.g. icons, responsive-table, viewport-aware-dropdowns)
- UI behaviours (e.g. motion, drag-and-drop, sortable-table)
- UI components (e.g. accordion, dialog, menu, tabs, carousel)
- User experience (e.g. form-factor-adaptation, natural-interactions)
- Visual design (e.g. typography, contrast-color, visually-stable-font-fallbacks)
- WebAssembly (e.g. cpp-on-the-web)
- WebMCP (e.g. webmcp, agentic-forms)

## Does it work

Chrome's eval suite (as of 9 Nov 2026): unguided agents pass about 52% of checks, guided agents about 91%. Reported results: WeTV (Tencent): 90% failed performance checks fixed automatically in CI; WeTV (Tencent): 87% less time to debug and fix (4 h → 30 min); note inc.: 94% pass rate on modern web checks, 180 runs (from 61%); Policybazaar: 92% less manual auditing across ~30 landing pages.

## Install and use

- Install: `npx modern-web-guidance@latest install` (Interactive wizard: picks your coding agent and installs the skills.)
- Update: `npx modern-web-guidance@latest update` (Bring an existing installation up to date.)
- Search: `npx modern-web-guidance@latest search "animate a dialog modal backdrop"` (Find the guide for a task.)
- Scan a project: `npx modern-web-guidance@latest legacy-scan .` (List legacy patterns worth modernizing.)
- In your agent: `/modern-web-guidance Modernize the code in this directory` (Ask the agent to modernize the current directory.)

## FAQ

### What is Modern Web Guidance?

A set of skills and a command-line tool for AI coding agents, published by the Chrome team and stewarded with Microsoft Edge, Mozilla Firefox and MDN. It gives agents expert-reviewed guides on modern web features and browser compatibility, so they use the platform's own APIs instead of the legacy patterns that dominate their training data.

### Which coding agents does it work with?

It installs through its CLI (npx modern-web-guidance@latest install) and through the plugin marketplaces of Claude Code, Codex, Cursor, Antigravity, GitHub Copilot, WebStorm, Kimi Code and Grok Build.

### Does it actually improve the code?

In Chrome's own eval suite, agents passed about 52% of the checks without it and about 91% with it (as of 9 Nov 2026), a gain of 39 points. Each guide defines expectations, and the same prompt is run with and without the guidance. These are Chrome's figures; test it on your own codebase too.

### What does it cover?

262 modern web features and 204 real-world use cases across accessibility, CSS, forms, HTML, JavaScript, performance, privacy, PWAs, security, UI components and behaviours, visual design, WebAssembly, built-in AI and WebMCP.

### Is it safe to use new APIs if some visitors have older browsers?

The guides favour progressive enhancement: purely additive features are simply ignored by older browsers, and critical behaviour gets a small fallback (under 50 lines) or a polyfill loaded only when needed. Compatibility comes from the Baseline project's live data, and experimental features stay off until you opt in.

### Can it update an existing website?

Yes. Version 1.0 adds a modernization workflow that scans HTML, CSS, JavaScript and package.json for safe upgrades. The first release uses static analysis on a limited set of patterns, so review its suggestions like any other change.

### Is it free?

Yes. It is open source under the Apache 2.0 licence.

## Sources

- [Modern Web Guidance on GitHub (README)](https://github.com/GoogleChrome/modern-web-guidance) (GoogleChrome)
- [Modern Web Guidance 1.0: the web platform expertise your coding agent is missing](https://developer.chrome.com/blog/modern-web-guidance-v1) (Chrome for Developers)
- [Top 10 things AI gets wrong in web development](https://developer.chrome.com/blog/top-10-things-ai-gets-wrong-in-web-dev) (Chrome for Developers)
- [Beyond code generation: using Modern Web Guidance for continuous developer learning](https://developer.chrome.com/blog/beyond-code-generation) (Chrome for Developers)
- [ICYMI: Modern Web Guidance is now stable](https://developer.chrome.com/blog/modern-web-guidance-recap) (Chrome for Developers)
- [Modern Web Guidance documentation](https://developer.chrome.com/docs/modern-web-guidance) (Chrome for Developers)
- [Eval dashboard](https://googlechrome.github.io/modern-web-guidance-src/) (GoogleChrome)
- [Source repository and issues](https://github.com/GoogleChrome/modern-web-guidance-src) (GoogleChrome)
