One Open Source Project a Day (No. 259): Modern Web Guidance — Chrome's Modern Web Best Practices for 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.

Have AI write front-end code and you will often see a familiar oddity: it runs, but it feels old. Dialogs position themselves with hand-written JavaScript when browsers have a native answer; animation and accessibility lean on piles of libraries the platform already covers. The cause is simple: the model's training data holds far more old code than new.

The project's idea is not to change the model, but to feed curated modern web guidance into the agent's context while it works. What makes it more interesting is that it ships more than content: it includes an evaluation pipeline that tries to show whether the guidance actually helps. This article follows the README and repo docs; I did not install it or run these commands.

What You Will Learn

• What problem Modern Web Guidance solves, and how it differs from letting a model "look up the docs itself"
• How the two-step search and retrieve flow works, and why it runs offline
• How it handles compatibility risk with new features: progressive enhancement, fallbacks, and gating
• The built-in evaluation pipeline, and how to read the officially published improvement numbers
• How to install it into Claude Code, Codex, and other agents

Prerequisites

• Having used Claude Code, Codex, or a similar AI coding agent, and knowing what a Skill is
• Basic familiarity with front-end work and browser APIs
• Optional: knowing what Baseline (browser compatibility baseline) means

Project Background

What It Is

Modern Web Guidance is a set of Skills that bring 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 together with the wider web community.

Note how the repos are split. The modern-web-guidance-src repo linked here is the source repository: it holds guide drafts, scripts, the evaluation harness, base example apps, and CLI tooling, and all issues and PRs go there. A separate GoogleChrome/modern-web-guidance is a read-only distribution repo with the compiled Skills and plugin configs. Merged changes are published weekly to the distribution repo and to the npm package modern-web-guidance.

Project Stats

• ⭐ GitHub Stars: about 4,045
• 🍴 Forks: about 238
• 💻 Language: TypeScript
• 📅 Created: 2026-01-27; last pushed 2026-11-13, so it is actively updated
• 📄 License: code is Apache-2.0; guide content under guides/ is CC-BY 4.0
• 👤 Maintainer: GoogleChrome, which the README says is maintained with the Chrome, Edge, Firefox, and MDN teams
• 🔗 Docs: a dedicated page on developer.chrome.com (see links below)

What It Does

The Problem It Solves

Without guidance:
  The agent writes from training data → leans toward old patterns, heavy JavaScript, extra libraries
  ↑ even when it knows an API exists, it lacks enough modern real-world examples
 
With guidance:
  The agent hits a web platform question → calls the CLI → gets a curated guide
  ↓ the guide has code patterns, gotchas, and fallbacks
  ↑ output is closer to modern, production-ready code

Quick Start

Interactive install:

npx modern-web-guidance@latest install

Or 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 a guide by ID
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"
 
# Scan the current project for legacy patterns
npx modern-web-guidance@latest legacy-scan .

After installing, the agent activates the modern-web-guidance Skill on relevant tasks and is told to use the CLI for web platform questions. Update with npx modern-web-guidance@latest update.

Other Ways to Install

The README gives entry points for several tools:

Two Skill packs are available, selected with install --choose: modern-web-guidance (browser APIs, layout, performance) and chrome-extensions (Manifest V3, workers, extension APIs, store publishing).

What It Covers

The README lists 250 modern web features (140 in CSS and layout, 36 in HTML and DOM, 74 in JavaScript and APIs) and 203 real-world developer use cases. Guides are grouped 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, and webmcp. In the distribution repo a guide path looks like skills/modern-web-guidance/guides/ui-components/navigation-drawer.md.

A Deeper Look

Two-Step Retrieval: search, Then retrieve

1. Activate: the agent enables the Skill on relevant tasks and is told to use the CLI for web platform questions
2. search: an offline, zero-dependency embedding model plus BM25 matches a natural language query to the best guide, with no network calls and no API key
3. retrieve: takes a guide ID and puts code patterns, gotchas, and fallbacks into the agent's context

The npm package is self-contained with no extra dependencies, which the README says is for low latency and supply-chain security. Using npx keeps content from going stale, while the CLI itself can run offline.

Principles for Adopting New Features Safely

The biggest risk with new APIs is compatibility. The project turns "how to use them safely" into a few rules:

• Progressive enhancement: purely additive features can be silently ignored by older browsers; for features that affect critical behavior, give a considered, low-overhead fallback
• Prefer light fallbacks: custom fallback code under 50 lines, or conditionally loaded polyfills, rather than heavy dependencies
• Document gotchas: for example fetchLater() has a 64KB payload quota, and macOS has its own scrollbar behavior
• Baseline-aware: use Baseline compatibility data so the agent adapts to current real support
• Gating: for Origin Trial or volatile features (single-engine features shipped within the last 3 months, or still stabilizing), search can find them but retrieve requires developer consent by default

Consent can be recorded in .mwgrc in the project root (or ~/.mwgrc at user level):

# Allow Origin Trial guides
npx modern-web-guidance@latest set-allow-origin-trials
# Allow volatile single-engine feature guides
npx modern-web-guidance@latest set-allow-volatile-features

The file can be committed so a team shares the same settings.

The Built-in Closed-Loop Evaluation

This is the part I find most worth learning from. Most Skill projects deliver content only; this one turns "does the content help" into a pipeline:

1. Experts write the guides
2. Evaluation targets are generated: tasks, golden solutions, and Playwright graders
3. Self-calibration: a grader must pass 100% of the golden solutions and fail 100% on the unmodified base app, or it is rejected
4. End-to-end runs: agents do tasks in "guided" and "unguided" modes, on two base apps, daily-grind and devtools-times, with prompts that avoid naming specific APIs
5. Iterate by metric:

Guides for things agents already do correctly are pruned; weak ones are refined. The graders check source patterns, computed styles, runtime DOM behavior, and accessibility states.

How to Read the Published Results

The README has a dated results table. The batch I saw is from November 8:

The README summarizes this as roughly +27 to +36 points. Keep these in mind:

• This is the project's own evaluation, using tasks and graders it designed, not a third-party benchmark
• The same team wrote the tasks, the guides, and the graders, so the result supports "it helps on these tasks" but does not promise the same gain on your own code
• The model versions in the table are quoted from the README, and I did not verify them
• The evaluation keeps updating, and the page has dashboards broken down by agent and by guide

Telemetry

The README says plainly that it collects anonymous data: install counts, agent name, retrieved guide IDs, and agent-generated search queries; raw user prompts are not collected. Opt out by setting the environment variable DISABLE_TELEMETRY=1. Before using it on company projects, check whether this meets your compliance requirements.

If You Want to Contribute

From CONTRIBUTING.md:

• Brand-new guides are in principle limited to onboarded Peers unless a Content ATL or Owner approves; anyone can file issues or send PRs improving existing guides
• Content work covers use cases, guide.md, demo.html, expectations.md, and self-validation
• A signed Google CLA is required before merge, even for docs-only changes
• Local development needs pnpm and Node.js >=22.18.0, and the full gate is pnpm preflight (build, typecheck, lint, unit tests)

Limits and Cautions

1. The evaluation numbers come from the project itself and are updated continuously, so they will change
2. However broad, the guides cover only about 250 features and 203 use cases; anything outside still depends on the model
3. Gating of new features relies on the developer's judgment, and once enabled, compatibility risk is yours
4. Telemetry is on by default and must be turned off by hand
5. The README presents the project as active but does not mark it beta or stable, so judge maturity yourself

Project Links and Resources

• 🌟 Source repo: https://github.com/GoogleChrome/modern-web-guidance-src
• 📦 Distribution repo (read-only): GoogleChrome/modern-web-guidance
• 📚 Docs: the repo points to a dedicated page on developer.chrome.com (goo.gle/modern-web-guidance)
• 📊 Eval dashboard: linked from the README
• 📄 License: code Apache-2.0, guide content CC-BY 4.0

Summary

Key Takeaways

1. The problem is well aimed: AI writes dated front-end code because of its training data, so the fix goes into the context
2. Two-step retrieval: offline search plus retrieve, with no network or key
3. Safe adoption of new features: progressive enhancement, light fallbacks, Baseline data, and gating for unstable features
4. Content and evaluation together: whether a guide helps is tested with guided-versus-unguided runs, which drive pruning and refinement
5. Discount the numbers: +27 to +36 points is the project's own evaluation, not a third-party conclusion

Who This Is For

• Developers who use AI agents for front-end work and find the output dated or heavy
• Anyone who wants to turn team front-end practices into a Skill
• Developers who want to learn how to evaluate Skill content; this closed loop is worth borrowing

Suggested First Steps

Skip the install at first and use search on a few needs from your own work, such as "modal dialog" or "scroll-driven animation," to judge the quality of what comes back. Then run legacy-scan . on one of your projects to see what it considers legacy. Finally, read docs/EVALS.md, which is the most distinctive part of the project.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage