A common problem when coding agents generate web pages is this: LLM training data contains vast amounts of legacy patterns, so agents generate unnecessarily heavy JavaScript for tasks already solvable with native browser APIs. Modern Web Guidance, a jointly managed open-source project by Google Chrome, Microsoft Edge, Mozilla Firefox, and MDN teams, is designed to close this gap.
With over 3,400 stars, this project processes 250 modern web features and 203 real-world developer use cases through local embeddings and BM25 search. It runs offline with zero network calls, and the npm package is self-contained—no supply-chain security risk.
Why it matters: from legacy patterns to modern APIs
LLMs generate code based on massive training data, which includes decades-old patterns. For example, when asked to "animate a dialog modal backdrop," an agent might load a full animation library, draw directly on canvas, or use jQuery-style DOM manipulation—when CSS View Transitions, the Popover API, or native dialog controls would suffice.
Modern Web Guidance injects targeted guides into the agent's context window across six core disciplines:
| Discipline | Key Features |
|---|---|
| UX | View Transitions, entry/exit animations, CSS scrollbar-color, parallax scroll |
| CSS Layout | Container queries, subgrid, oklch color spaces, text-wrap, line-height trimming |
| Performance | Speculative preloading, INP diagnostics, scheduler.yield |
| Forms & UI | Anchor Positioning, Popover API, dialogs, :user-invalid, auto-sizing fields |
| Accessibility | Screen reader and keyboard operability, content navigation and discoverability |
| Built-in AI | Native translation, summarization, language detection APIs |
Notably, "Responsible Fallbacks" is a key concept. Purely additive enhancements (like speculative preloading) can be silently ignored by older browsers, but critical behaviors (dialog controls, network beacons) should have lightweight, case-specific fallbacks—typically under 50 lines of code—instead of heavy third-party bundles.
How it works: search, retrieve, inject
Three CLI commands:
# Search for relevant guides
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 a codebase for legacy patterns
npx modern-web-guidance@latest legacy-scan .
search matches queries to the best guide using an offline embedding model and BM25 search. retrieve injects code patterns, gotchas, and fallbacks into the context window. legacy-scan scans an entire codebase for legacy patterns to modernize.
Running via npx always provides the latest content, but the package works fully offline with no network calls or API keys required.
Evaluation: unguided vs. guided, how much does it matter?
The project developed its own eval harness to empirically verify content quality. The structure defines simulated developer tasks against full base applications, then uses Playwright graders to verify implementation requirements.
Recent eval results snapshot:
| Date | Agent + Model | Tasks / Assertions | Unguided → Guided (Uplift) |
|---|---|---|---|
| Nov 8 | antigravity_cli (gemini-4-argon) | 214 / 1,673 | 58% → 94% (+36pp) |
| Nov 8 | codex_cli (gpt-6.1-sol) | 215 / 1,795 | 54% → 82% (+28pp) |
| Nov 8 | claude_code (opus-5-5) | 215 / 1,801 | 57% → 88% (+31pp) |
| Nov 6 | codex_cli (gpt-6.1-sol) | 212 / 1,773 | 53% → 86% (+33pp) |
| Nov 6 | claude_code (opus-5-5) | 212 / 1,773 | 56% → 90% (+34pp) |
antigravity_cli (gemini-4-argon) achieved the highest uplift at +36pp. Codex (gpt-6.1-sol) and Claude Code (opus-5-5) also showed consistent +28–34pp gains. Guided mode achieves 82–96% pass rates across agents.
These numbers are published by the project. CodeBridge did not reproduce them with the same eval harness. The key metrics are "opportunity" (100% − unguided pass rate) and "uplift" (guided − unguided pass rate).
Configuration: managing Origin Trial and volatile features via .mwgrc
Per-repository opt-in for Origin Trial and volatile features is managed through a .mwgrc JSON file:
{
"allowOriginTrials": true,
"allowVolatileFeatures": true
}
Origin Trial APIs are discoverable via search but require explicit opt-in for retrieve. Volatile features (single-engine features shipped within the last 3 months or still stabilizing) are handled the same way. This prevents agents from adopting unstable APIs without explicit developer consent.
Telemetry and opt-out
Google collects anonymous usage data: installation counts, calling agent name, guide retrieval IDs, and CLI search queries (e.g., "dark mode scrollbar color-scheme"). Raw user prompts are not collected.
Opt-out is available via environment variable:
export DISABLE_TELEMETRY=1
Practical use cases
Modern Web Guidance is most effective when coding agents are used in projects where legacy patterns are frequently generated. Consider it when:
- Introducing agents to new codebases: Initial guide installation teaches agents to use modern APIs as defaults.
- Gradual modernization of legacy codebases: Use
legacy-scanto identify problem areas, then apply guides to the modification scope. - Team standardization: Commit
.mwgrcto the repository so all members use the same modern web baseline.
However, independent evidence that all agents produce higher-quality code has not yet been confirmed. The evals were conducted within the project's own harness; reproduction results on actual production codebases are separate.
Limitations: the scope of the eval harness
First, the eval is based on simulated developer tasks. Prompts like "my images load faster" avoid naming APIs or features, testing whether agents can naturally discover the right guides. But this doesn't fully replace more complex real-world scenarios (performance bottlenecks, accessibility audits, browser-specific bugs).
Second, "250 features" and "203 use cases" represent the project's curated scope. Not every modern web feature is covered. Single-engine-only features are classified as volatile and require opt-in for retrieve.
Third, telemetry collection is enabled by default. While opt-out is available, organizational policies may require reviewing what external tools collect.
Insight: improving knowledge quality without changing the model
Modern Web Guidance's approach is notable. Instead of replacing or fine-tuning the model, it improves the quality of technical knowledge provided to agents. Injecting 250 features and 203 use cases via local embeddings into the context is similar to real-time correction of the model's training data quality.
When evaluating adoption, the question is not "does Modern Web Guidance improve agent code quality?" but "what legacy patterns does my agent frequently generate, what problems does legacy-scan reveal, and is the guided/unguided pass rate uplift meaningful for my work?" Running legacy-scan on an existing project and checking browser compatibility is the first step.
For more on web agent structures, see the Agent Flow course for observe-act-verify patterns.