Chrome's Modern Web Guidance Shoves Curated Best Practices Into AI Coding Agents
Introduction
"Keep your coding agent up to date with the latest web best practices."
This is the 259th article in the "One Open Source Project a Day" series. Today's project is GoogleChrome's Modern Web Guidance.
When you ask AI to write frontend code, a common awkward thing happens: what it produces runs, but feels "old." For popups, it computes positions using JavaScript when browsers already have native solutions; for animations and accessibility, it leans on a pile of libraries when the platform itself already supports them. The reason is straightforward: training data contains far more old code than new patterns.
This project's approach: instead of modifying the model, feed the agent curated modern Web guidance into its context while it works. More interestingly, it doesn't just provide content—it ships a built-in evaluation pipeline with data showing whether "feeding the guidance" actually helps. This article is based on the README and repository docs; I have not installed and run these commands myself.
What you'll learn
- What problem Modern Web Guidance solves, and how it differs from just telling the model to "look up the docs itself"
- How the two-step
searchandretrieveretrieval works, and why it runs offline - How it handles compatibility risks of new features: progressive enhancement, fallbacks, and gating
- The project's built-in evaluation pipeline and how to read the official improvement numbers
- How to install it into Claude Code, Codex, and other agents
Prerequisites
- Familiarity with Claude Code, Codex, or similar AI coding agents, and the concept of Skills
- Basic knowledge of frontend and browser APIs
- Optional: familiarity with Baseline (browser compatibility baseline)
Project Background
Project Overview
Modern Web Guidance is a set of Skills that feed Web platform knowledge, best practices, and browser compatibility data into AI coding agents. The README says it is maintained by the Chrome, Edge, Firefox, and MDN teams along with the broader Web community.
Note the repository division: the modern-web-guidance-src linked here is the source repository, containing guide drafts, scripts, evaluation framework, sample base apps, and CLI tooling. All issues and PRs go here. The other, GoogleChrome/modern-web-guidance, is a read-only release repository holding compiled Skills and plugin configuration. Merged changes are published weekly to the release repository and the npm package modern-web-guidance.
Project Data
- ⭐ GitHub Stars: ~4,045
- 🍴 Forks: ~238
- 💻 Language: TypeScript
- 📅 Created: 2026-01-27, last push 2026-11-13, still actively updated
- 📄 License: Code Apache-2.0; guide content under
guides/is CC-BY 4.0 - 👤 Maintainer: GoogleChrome, with README crediting Chrome, Edge, Firefox, and MDN teams
- 🔗 Docs: dedicated page on developer.chrome.com (see project link)
Main Features
The Problem It Solves
Without guidance:
Agent codes from training data → biases toward older patterns, heavy JavaScript, unnecessary libraries
↑ Even if it knows an API exists, it lacks enough modern, real-world examples
With guidance:
Agent hits a Web platform problem → calls CLI retrieval → gets curated guides
↓ Guides contain code patterns, pitfalls, fallback approaches
↑ Output is closer to modern, production-ready code
Quick Start
Interactive install:
npx modern-web-guidance@latest install
Try the three subcommands without installing:
# Search for the best-matching guide by description
npx modern-web-guidance@latest search "animate a dialog modal backdrop"
# Retrieve full guide by ID
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"
# Scan current project for legacy patterns
npx modern-web-guidance@latest legacy-scan .
After installation, the agent activates the modern-web-guidance Skill for relevant tasks and is instructed to use the CLI when hitting Web platform problems. Update with npx modern-web-guidance@latest update.
Other Installation Methods
The README gives install entry points for several tools:
| Tool | Command or method |
|---|---|
| Vercel Skills CLI | npx skills add GoogleChrome/modern-web-guidance |
| GitHub CLI | gh skill install GoogleChrome/modern-web-guidance |
| OpenAI Codex | codex plugin marketplace add GoogleChrome/modern-web-guidance, then codex plugin add modern-web-guidance@googlechrome |
| Claude Code | Via plugin marketplace, then enable auto-update in /plugin and /reload-plugins |
| GitHub Copilot CLI | /plugin marketplace add, then /plugin install modern-web-guidance@googlechrome |
| Google Antigravity | agy plugin install <repo URL> |
| Grok Build CLI | grok plugin install <repo URL> --trust |
| Kimi Code | /plugins install <repo URL> |
Additionally, two optional Skill packages can be chosen with install --choose: modern-web-guidance (browser APIs, layout, performance) and chrome-extensions (Manifest V3, Workers, extension APIs, store publishing).
Content Coverage
The README lists the scale: 250 modern Web features (140 CSS & layout, 36 HTML & DOM, 74 JavaScript & API) and 203 real-world development scenarios. Guides are organized by category: accessibility, built-in-ai, css, forms, html, js, performance, privacy, pwa, security, ui-atoms, ui-behaviors, ui-components, user-experience, visual-design, wasm, webmcp. Guides in the release repository follow paths like skills/modern-web-guidance/guides/ui-components/navigation-drawer.md.
Detailed Analysis
Two-Step Retrieval: First search, then retrieve
- Activation: The agent enables the Skill for relevant tasks and is told to use the CLI to answer Web platform questions.
- search: Uses an offline, zero-dependency embedding model plus BM25 to match natural language queries to the most relevant guides. No network, no API key needed.
- retrieve: Pulls the guide's code patterns, pitfalls, and fallbacks into the agent's context by guide ID.
The npm package is self-contained with no extra dependencies, which the README says is for low latency and supply-chain security. Using npx ensures content doesn't go stale while the CLI itself can operate offline.
Principles for Safely Adopting New Features
The biggest risk with new APIs is compatibility. The project codifies "how to use them safely" into rules:
- Progressive enhancement: Purely additive features can be silently ignored by old browsers; those affecting critical behavior need a considered, low-cost fallback.
- Prefer lightweight fallbacks: Keep custom fallback code under 50 lines, or conditionally load a polyfill, rather than pulling in heavy dependencies.
- Document pitfalls: e.g.,
fetchLater()has a 64KB payload quota, and there are macOS-specific scrollbar behaviors. - Baseline-based: Uses Baseline compatibility data to let the agent adjust according to current real-world support.
- Gating: For Origin Trials or unstable features (released only in a single engine within the last 3 months, or still in stabilization),
searchcan find them, butretrieverequires explicit developer consent by default.
Consent can be written to a project-root .mwgrc (or user-level ~/.mwgrc):
# Allow Origin Trial guides
npx modern-web-guidance@latest set-allow-origin-trials
# Allow unstable single-engine feature guides
npx modern-web-guidance@latest set-allow-volatile-features
This file can be committed to the repo, letting the whole team share the same settings.
Built-in Closed-Loop Evaluation
This is the part I found most valuable. Most Skill projects just deliver content; this one turns "is the content useful" into a pipeline:
- Experts write guides
- Automatically generate eval targets: tasks, golden solutions, Playwright scoring scripts
- Self-calibration: scoring scripts must pass 100% on the golden solution and fail 100% on the unmodified base app, or they're rejected
- End-to-end run: Agents complete tasks in "with guidance" and "without guidance" modes, using two base apps (
daily-grindanddevtools-times), with prompts that don't name specific APIs - Iterate on metrics:
| Metric | Meaning |
|---|---|
| opportunity | 100% minus the no-guidance pass rate; represents remaining headroom for improvement |
| uplift | With-guidance pass rate minus no-guidance pass rate |
Guides agents already handle correctly get trimmed; weak guides get improved. Scoring scripts check source patterns, computed styles, runtime DOM behavior, and accessibility states.
How to Read the Official Results
The README has a date-updated results table; the batch I saw was from November 8:
| Agent | No guidance → With guidance | Uplift |
|---|---|---|
| antigravity_cli | 58% → 94% | +36 points |
| claude_code | 57% → 88% | +31 points |
| codex_cli | 54% → 82% | +28 points |
The README itself summarizes as roughly +27 to +36 percentage points. Keep in mind when reading these numbers:
- This is the project's own evaluation, using its own tasks and scoring scripts, not a third-party benchmark.
- The task set is written by the same team; guides and evals share a common origin. The results are convincing for "effective on these tasks" but guarantee nothing about "your business code will improve by the same amount."
- The model versions in the table are as written in the README; I haven't verified them.
- Evaluations are continuously updated; the page also has dashboards split by agent and guide.
Telemetry
The README explicitly says anonymous data is collected: installation counts, agent name, retrieved guide IDs, and search queries generated by agents. Raw user prompts are not collected. To disable, set the environment variable DISABLE_TELEMETRY=1. Before using in a company project, it's worth confirming this meets your compliance requirements.
Want to Contribute Content?
Key points from CONTRIBUTING.md:
- Brand-new guides are generally only open to already-onboarded Peers unless authorized by the Content ATL or Owner; anyone can file an issue or submit a PR for existing guides.
- Content work includes use cases,
guide.md,demo.html,expectations.md, and self-review. - Google CLA must be signed before merging, even for pure doc changes.
- Local development requires pnpm and Node.js
>=22.18.0; the full check command ispnpm preflight(build, type check, lint, unit tests).
Limitations and Caveats
- Evaluation data comes from the project itself and is continuously updated; numbers will change.
- However large the guide coverage, it's still ~250 features and 203 scenarios; problems not in the list still fall back to the model.
- Gating of new features relies on developer judgment; enabling them means you take on compatibility risk.
- Telemetry is on by default and must be manually turned off.
- The README describes the project as active but doesn't mark it beta or stable; assess maturity yourself before using.
Project Links and Resources
- 🌟 Source repo: https://github.com/GoogleChrome/modern-web-guidance-src
- 📦 Release repo (read-only): GoogleChrome/modern-web-guidance
- 📚 Docs: Repo home points to a dedicated page on developer.chrome.com (
goo.gle/modern-web-guidance) - 📊 Eval dashboard: Linked from README
- 📄 License: Code Apache-2.0, guide content CC-BY 4.0
Summary and Outlook
Key Points Recap
- Problem identification is accurate: AI frontend code skews old because of training data, so the fix is to supplement via context.
- Two-step retrieval: Offline
searchplusretrieve, no network or keys required. - Safe adoption of new features: Progressive enhancement, lightweight fallbacks, Baseline data, plus gating for unstable features.
- Content and evals integrated: Whether guides work is validated by with/without-guidance controlled experiments to trim and improve.
- Read numbers with a grain of salt: +27 to +36 points is the project's own evaluation, not a third-party conclusion.
Who It's For
- Developers who regularly use AI agents for frontend work and find the output stale or bloated.
- People who want to distill their team's frontend best practices into a Skill.
- Developers wanting to learn "how to build evals for Skill content"—this closed loop is worth borrowing.
Learning Suggestions
Before installing, try search with a few common requirements from your work, like "modal" or "scroll-driven animations," and see the quality of returned guides. Then run legacy-scan . on your own project to see which patterns it calls old. Finally, read docs/EVALS.md—that's the most distinctive part of the project.
Visit PrimeSkills — a curated marketplace for AI agents and skills, with everything validated by real enterprise-grade workflows. No gimmicks, only what actually works.
For more practical knowledge and interesting products, visit my personal homepage