# Modern Web Guidance

> An open-source agent skill and CLI that guides AI coding agents to use modern, high-performance, accessible, and secure web platform APIs instead of legacy workarounds.

Modern Web Guidance is an open-source project supported by the Google Chrome team, the Microsoft Edge team, and the web development community. It ships as an agent skill (a `SKILL.md` file) paired with a CLI that injects expert-curated, token-efficient web platform guidance directly into a coding agent's context window. The project is in early preview and actively adding new content, with contributions welcomed on GitHub.

## What It Is

Modern Web Guidance addresses a specific problem: coding agents frequently default to outdated JavaScript patterns because LLM training data contains large volumes of legacy code. Even when a model knows a modern API exists, it often lacks the density of real-world implementation patterns needed for production-ready output. The skill bridges this gap by providing targeted, expert-vetted guidelines covering modern browser APIs, CSS layout systems, performance optimizations, accessibility patterns, forms and UI components, and built-in AI APIs. The published distribution is compiled and released to the `GoogleChrome/modern-web-guidance` repository; the source repository (`GoogleChrome/modern-web-guidance-src`) is where guidance is authored, calibrated, and evaluated.

## How It Works

The workflow has three steps once the skill is installed:

- **Activation**: The coding agent detects a relevant web platform task and activates the `modern-web-guidance` skill.
- **Local Semantic Search**: The agent runs `modern-web search "<query>"`. An offline, CPU-efficient TensorFlow.js model matches the query to the best guide — no network calls, no API keys required.
- **Guide Fetch**: The agent runs `modern-web retrieve <guide-id>`, pulling targeted code patterns, gotchas, and fallbacks directly into its context window.

The NPM package is self-contained with no extra dependencies, keeping latency low and supply-chain risk minimal. Telemetry (search queries, guide retrievals, installation events) is collected anonymously by Google and can be disabled by setting `DISABLE_TELEMETRY=1`.

## Core Disciplines Covered

The guidance spans six areas:

- **User Experience**: View Transitions, entry/exit animations, parallax scroll, CSS `scrollbar-color`
- **CSS Layout**: Container queries, `subgrid`, modern color spaces like `oklch`, text-wrap tuning, line-height trimming
- **Performance**: Instant preloading, Interaction to Next Paint (INP) diagnostics, `scheduler.yield`
- **Forms & UI**: Anchor Positioning for tooltips, Popover API, dialogs, `:user-invalid` validation, auto-sizing fields
- **Accessibility**: Accessible error announcements, keyboard focus management
- **Built-in AI**: Native translation, summarization, and language detection APIs

Guides are designed to be token-efficient; an eval pipeline prunes content that models already handle well, so only high-value guidance reaches the context window.

## Eval Harness and Measured Uplift

The project includes a closed-loop evaluation pipeline to empirically validate that the guidance improves agent output. The pipeline authors realistic developer prompts that avoid naming specific APIs, runs browser-based Playwright assertions against generated code, and compares agent accuracy in guided versus unguided modes. The project publishes a snapshot of recent eval results: according to the repository, runs in May 2026 using `claude_code` with `opus-4-7` across 75 tasks and 603 assertions showed unguided pass rates of roughly 51–54% rising to 85–86% with guidance (uplifts of +31 to +35 percentage points). Runs with `codex_cli (gpt-5.5)` showed similar uplifts of +29 to +33 percentage points.

## Installation and Skill Packs

The recommended install path is `npx modern-web-guidance@latest install`, which runs an interactive wizard. Alternative methods include Vercel's `npx skills` CLI, GitHub CLI (`gh skill install`), Google Antigravity CLI, GitHub Copilot CLI, and Claude Code plugin commands. Two skill packs are available via the `--choose` flag:

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

The project also integrates with Chrome DevTools for agents, enabling real-time performance audits, accessibility tree inspection, and console log capture alongside modern web code fixes.

## Features
- Agent skill (SKILL.md) for coding agents
- CLI for local semantic search and guide retrieval
- Offline TensorFlow.js semantic search (no API keys)
- Token-efficient, expert-curated web platform guides
- Modern Browser APIs guidance
- CSS layout guidance (container queries, subgrid, oklch)
- Performance optimization guidance (INP, scheduler.yield, preloading)
- Forms & UI guidance (Popover API, Anchor Positioning, dialogs)
- Accessibility patterns
- Built-in AI APIs guidance (translation, summarization, language detection)
- Progressive enhancement and responsible fallbacks
- Baseline-aware browser compatibility integration
- Closed-loop eval harness with Playwright assertions
- Chrome Extensions (Manifest V3) skill pack
- Interactive install wizard
- Telemetry opt-out via DISABLE_TELEMETRY=1

## Integrations
Claude Code, GitHub Copilot CLI, Vercel Agent Skills (npx skills), Google Antigravity CLI, Chrome DevTools for agents, TensorFlow.js, Playwright, Baseline (browser compatibility data)

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://goo.gle/modern-web-guidance
- Documentation: https://developer.chrome.com/docs/modern-web-guidance/get-started
- Repository: https://github.com/GoogleChrome/modern-web-guidance-src
- EveryDev.ai: https://www.everydev.ai/tools/modern-web-guidance