Modern Web Guidance (Source)

A unified repository for authoring, calibrating, and evaluating modern web development guidance. Here, we curate and codify best practices, write eval tasks and assertions, and an evaluation harness measures how coding agents follow the guidance.

The published distribution of this guidance is compiled and released to the GoogleChrome/modern-web-guidance repository as agent skills including the primary modern-web-guidance skill (which utilizes a bundled CLI distribution) alongside other standalone skills.

See CONTRIBUTING.md for how we work on the project and orientation of the codebase. We're open to contributions to guidance, eval cases, eval infra and more. :)

---

Modern Web Guidance is an agent skill (aka SKILL.md) with a CLI that helps coding agents build better web applications using modern, high-performance, accessible, and secure APIs instead of legacy workarounds.

Supported by the Google Chrome team, the Microsoft Edge team, and the web development community.

Quickstart

npx modern-web-guidance@latest install

This command runs an interactive wizard to place the SKILL.md appropriately. See Alternative Installation Methods below.

Try it out (without installing)

# 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"

Why?

Coding agents often default to older patterns because LLM training data contains vast amounts of legacy code. This often leads them to generate bloated JavaScript for tasks that now have native, high-performance web platform solutions.

Even if a model knows an API exists, it often lacks the density of real-world, modern implementation patterns required for production-ready code.

Modern Web Guidance bridges this gap. Our skill's CLI returns targeted, expert-curated guidelines directly into your agent's context window, focusing on:

• Modern Browser APIs: Helping models correctly structure APIs they frequently misuse.
• Performance & Accessibility: Eliminating legacy bloat with clean, native patterns.
• Responsible Fallbacks: Guiding models to use sensible, lightweight fallbacks instead of heavy polyfills or legacy libraries.

What's Included?

We cover the past several years of the web platform's new features, all the way up to the cutting edge. The guides are designed to be token-efficient; we run evals enabling us to prune lowest-common-denominator content that models already know.

Core Disciplines

🎨 User Experience Smooth visual states (View Transitions, entry/exit animations, parallax scroll, CSS scrollbar-color).	📐 CSS Layout Modern layout systems (container queries, subgrid, modern color spaces like oklch, text-wrap tuning, and line-height trimming).	⚡ Performance Speed optimizations (instant preloading, Interaction to Next Paint (INP) diagnostics, and scheduling tasks via scheduler.yield).
📝 Forms & UI Native components (Anchor Positioning for tooltips, Popover API, dialogs, :user-invalid validation, and auto-sizing fields).	♿ Accessibility Hardened patterns (accessible error announcements, keyboard focus management).	🤖 Built-in AI Local client models (native translation, summarization, and language detection APIs).

View an example: the navigation-drawer guide.

Safe Adoption of Modern Features

• Progressive Enhancement & Nuanced Fallbacks: We distinguish between purely additive enhancements (like speculative preloading) which are safe to let older browsers silently ignore, and critical behaviors (like dialog controls or network beacons) where we write highly considered, low-overhead fallbacks.
• Responsible Fallbacks: We prioritize lightweight, case-specific custom fallbacks (<50 LOC) or conditionally-loaded polyfills instead of heavy third-party bundles.
• Gotchas & Quirks: We document hidden platform limitations, such as the 64KB payload quota for fetchLater() or macOS-specific scrollbar behaviors.
• Baseline-Aware Integration: We leverage real-time compatibility data from the Baseline project so agents can dynamically adapt to current browser support and any browser support preferences.

How It Works

0. Activation: The coding agent activates the modern-web-guidance skill because of a relevant task. The agent is instructed to use the modern-web CLI for web platform queries.
1. Local Semantic Search: The agent runs modern-web search "<query>". The tool matches the query to the best guide using an offline, CPU-efficient TensorFlow.js model (no network calls, no API keys).
2. Guide Fetch: The agent retrieves the guide via modern-web retrieve <guide-id>, inserting targeted code patterns, gotchas, and fallbacks directly into its context window.

Tip

Note: We use npx to ensure the content doesn't go stale, but the CLI works offline, completely private and local. The NPM package is self-contained, with no extra dependencies to ensure both low-latency and supply-chain security.

Alternative Installation Methods

Vercel Skills CLI (aka npx skills)

npx skills add GoogleChrome/modern-web-guidance

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

Google Antigravity

agy plugin install https://github.com/GoogleChrome/modern-web-guidance

GitHub Copilot CLI

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome

Claude Code Plugin

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin  # Select GoogleChrome marketplace, press enter, enable AutoUpdate
/reload-plugins

Updating

If you installed the skill using npx modern-web-guidance@latest install, you can update with: npx modern-web-guidance@latest update.

Otherwise, consult your agent's documentation for updating plugins and skills.

Evals to prove this works well ;)

We developed a robust eval harness to ensure that the content is empirically proven and continuously calibrated to ensure AI agents write better code. We run automated evaluations using a closed-loop validation pipeline:

  [ Expert-authored guidance and demo ]
            │
            ▼
  [ Generated assets ] ──> Playwright Grader (.spec.ts) & Negative Demo (.html)
            │
            ▼
  [ Calibration loop ] ───────> Runs Grader on Gold-Standard Demo (Must Pass 100%)
            │                   Runs Grader on Negative Demo (Must Fail 100%)
            ▼
  [ E2E agent evals ] ────────> Runs coding agents in guided vs. unguided modes
                                Compares accuracy w/ and w/o the skill

0. Simulated Developer Tasks: We define realistic, developer prompts that mimic real-world requests (e.g., "make my images load faster"). The prompts avoid naming APIs or features, testing whether the agent can successfully discover the relevant guides naturally.
1. Browser-based Assertions: We write browser automation scripts that verify the guide was followed correctly: exact runtime behaviors, computed styles, accessibility states, etc.
2. Self-Healing Calibration: Graders are calibrated against both a reference implementation (100% pass target) and a control page (0% pass target). The agent automatically refines tests on failure.
3. E2E Testing: We measure coding agent performance on real tasks with and without guidance. The opportunity (100% - unguided pass rate) and uplift (guided - unguided pass rate) are key. If there's little opportunity, then models already do a great job and our guidance isn't providing much value. Based on the results, we revise guides to maximize the uplift, optimizing their effectiveness.

Recent eval results snapshot

Date	Agent + Model	Tasks / Assertions	Unguided → Guided (Uplift)
May 18	claude_code (opus-4-7)	75 / 603	52% → 85% (+33pp)
May 17	claude_code (opus-4-7)	75 / 603	54% → 85% (+31pp)
May 16	codex_cli (gpt-5.5)	75 / 603	49% → 82% (+33pp)
May 16	claude_code (opus-4-7)	75 / 603	51% → 86% (+35pp)
May 15	codex_cli (gpt-5.5)	74 / 600	52% → 81% (+29pp)
May 15	claude_code (opus-4-7)	74 / 600	53% → 82% (+29pp)
May 15	Antigravity	74 / 600	47% → 91% (+44pp)
May 14	Antigravity	68 / 554	47% → 91% (+44pp)
Apr 30	claude_code (opus-4-6)	66 / 516	44% → 81% (+37pp)
Apr 28	claude_code (opus-4-6)	66 / 524	41% → 77% (+36pp)

Available Skill Packs

You can customize which skill packs are installed using the --choose flag:

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

• modern-web-guidance (~234 tokens): Comprehensive guidance on modern browser APIs, layouts, and performance.
• chrome-extensions (~181 tokens): Guidance on Manifest V3, background workers, extension APIs, and Chrome Web Store publishing.

Telemetry & Privacy

Google collects anonymous usage statistics (such as search queries, guide retrievals, and installation) to improve the reliability, relevance, and performance of the tool. You can inspect what is collected in modern-web.ts.

Tip

To Opt-Out:, set the DISABLE_TELEMETRY=1 env variable in your shell profile (e.g., .bashrc or .zshrc):

export DISABLE_TELEMETRY=1

Google handles this data in accordance with the Google Privacy Policy.

Contributors

If you'd like to contribute to modern-web-guidance, please see source repo's CONTRIBUTING.md. The modern-web-guidance repo is a purely a publish target for clean skills installation.

Huge thanks to everyone who has contributed!

License

Unless otherwise noted:

• Software code in this repository is licensed under the Apache License 2.0.
• Documentation and guide content under guides/ are licensed under Creative Commons Attribution 4.0 International (CC-BY 4.0).

Portions of the documentation in this project are derived from MDN Web Docs by Mozilla Contributors and W3C, WHATWG, and IETF specifications.