Quickstart
```shell
npx modern-web-guidance@latest install
```
This command runs an interactive wizard to install Modern Web Guidance. See [Alternative Installation Methods](#-alternative-installation-methods) below.
#### Try it out (without installing)
```shell
# 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 to modernize
npx modern-web-guidance@latest legacy-scan .
```
## 
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**: Preferring platform-level APIs that can be optimized by the browser and include built-in accessibility affordances.
* **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 ExperienceSmooth visual states (View Transitions, entry/exit animations, parallax scroll, CSS |
📐 CSS LayoutModern layout systems (container queries, |
⚡ PerformanceSpeed optimizations (instant preloading, Interaction to Next Paint (INP) diagnostics, and scheduling tasks via |
📝 Forms & UINative components (Anchor Positioning for tooltips, Popover API, dialogs, |
♿ AccessibilityImportant considerations (screen reader and keyboard operability, content navigation and discoverability). |
🤖 Built-in AILocal client models (native translation, summarization, and language detection APIs). |
How It Works
1. **Activation**: The coding agent activates the `modern-web-guidance` skill because of a relevant task. The agent is instructed to use the `modern-web-guidance` CLI for web platform queries.
2. **Local Semantic Search**: The agent runs `modern-web-guidance search " Alternative Installation Methods
npx skills)
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** so AI agents write better code. We run automated evaluations using a closed-loop validation pipeline:
```
[ Expert-authored guidance and demo ]
│
▼
[ Target generation ] ──> Tasks on real webapps, Golden solutions, Playwright graders
│
▼
[ Calibration loop ] ───> Runs Grader on Golden Solutions (Must Pass 100%)
│ Runs Grader on Unmodified Base App (Must Fail 100%)
▼
[ E2E agent evals ] ────> Runs coding agents in guided vs. unguided modes
Compares pass rates and accessibility w/ and w/o the skill
```
1. **Simulated Developer Tasks**: We define realistic developer prompts against full base applications (`daily-grind`, `devtools-times`) that mimic real-world requests (e.g., "make my images load faster"). Prompts avoid naming APIs or features, testing whether the agent can naturally discover and apply the right guides.
2. **Static & Browser-Based Assertions**: Playwright graders verify that each implementation requirement was followed—checking source patterns, computed styles, runtime DOM behaviors, and accessibility states.
3. **Self-Healing Calibration**: Graders are calibrated against multi-agent (Claude/Codex/AGY) golden solutions (100% pass target) and an unmodified baseline application (0% pass target).
4. **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 models already succeed without guidance, we prune redundant advice; where agents struggle, we refine guides to maximize uplift.
### Recent eval results snapshot
Explore full per-agent and per-guide breakdowns on the **[Eval Dashboard](https://googlechrome.github.io/modern-web-guidance-src/)**.
| Date | Agent + Model | Tasks / Assertions | Unguided → Guided (Uplift) |
| :--- | :--- | :---: | :---: |
| Nov 8 | antigravity_cli (gemini-4-argon) | 214 / 1673 | 58% → 94% (**+36pp**) |
| Nov 8 | codex_cli (gpt-6.1-sol) | 215 / 1795 | 54% → 82% (**+28pp**) |
| Nov 8 | claude_code (opus-5-5) | 215 / 1801 | 57% → 88% (**+31pp**) |
| Nov 6 | codex_cli (gpt-6.1-sol) | 212 / 1773 | 53% → 86% (**+33pp**) |
| Nov 6 | claude_code (opus-5-5) | 212 / 1773 | 56% → 90% (**+34pp**) |
| Nov 6 | antigravity_cli (gemini-4-argon) | 212 / 1722 | 60% → 96% (**+36pp**) |
| Nov 4 | codex_cli (gpt-6.1-sol) | 209 / 1743 | 52% → 85% (**+33pp**) |
| Nov 4 | claude_code (opus-5-5) | 209 / 1743 | 57% → 90% (**+33pp**) |
| Nov 4 | antigravity_cli (gemini-4-argon) | 207 / 1722 | 60% → 96% (**+36pp**) |
| Nov 2 | codex_cli (gpt-6.1-sol) | 205 / 1729 | 55% → 82% (**+27pp**) |
## 
Available Skill Packs
You can customize which skill packs are installed using the `--choose` flag:
```shell
npx modern-web-guidance@latest install --choose
```
* **`modern-web-guidance`** (~205 tokens): Comprehensive guidance on modern browser APIs, layouts, and performance.
* **`chrome-extensions`** (~175 tokens): Guidance on Manifest V3, background workers, extension APIs, and Chrome Web Store publishing.
## 
Telemetry & Privacy
Google collects anonymous usage information to improve the tool's reliability, relevance, and performance. Collected information includes installation counts, the calling agent name, guide retrieval IDs, and CLI tool search queries generated by the agent (e.g. "dark mode scrollbar color-scheme"). Raw user prompts are not collected. You can inspect what is collected in [modern-web.ts](https://github.com/GoogleChrome/modern-web-guidance-src/blob/main/src/cli/modern-web.ts).
> [!TIP]
> **To Opt-Out:** set the `DISABLE_TELEMETRY=1` env variable in your shell profile (e.g., `.bashrc` or `.zshrc`):
> ```bash
> export DISABLE_TELEMETRY=1
> ```
Google handles this data in accordance with the [Google Privacy Policy](https://policies.google.com/privacy).
## 
Contributors
Found a bug, outdated pattern, or missing web platform feature? [Open an issue](https://github.com/GoogleChrome/modern-web-guidance-src/issues) or see [`CONTRIBUTING.md`](https://github.com/GoogleChrome/modern-web-guidance-src/blob/main/CONTRIBUTING.md) in the [source repository (`GoogleChrome/modern-web-guidance-src`)](https://github.com/GoogleChrome/modern-web-guidance-src).
Huge thanks to everyone who has contributed!
License
Unless otherwise noted:
* Software code in this project is licensed under the [Apache License 2.0](https://github.com/GoogleChrome/modern-web-guidance-src/blob/main/LICENSE).
* Documentation and guide content under `guides/` are licensed under [Creative Commons Attribution 4.0 International (CC-BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
Portions of the documentation in this project are derived from [MDN Web Docs](https://developer.mozilla.org/) by Mozilla Contributors and [W3C](https://www.w3.org/), [WHATWG](https://whatwg.org), and [IETF](https://www.ietf.org) specifications.