Modern Web Guidance Explained

Modern Web Guidance is an open-source set of skills and a CLI from the Google Chrome team for coding agents. Before the agent writes a web app, it looks up current browser standards (the Popover API, <dialog>, CSS Anchor Positioning, container queries and more) together with compatibility data, which is meant to fix the habit of hand-building everything in 2019-style JavaScript. It is licensed under Apache-2.0 and installs with one line: npx modern-web-guidance@latest install.

According to Chrome's documentation it covers more than 100 use cases across UX, CSS, performance, forms, built-in UI components, accessibility, built-in AI and passkeys. The source repository (GoogleChrome/modern-web-guidance-src) had about 1.4k GitHub stars as of November 11, 2026, and a Show HN post about it was on the Hacker News front page the same day. This article relies on Chrome's official docs and the GitHub README to explain how it works, how to install it for each agent, how to use it, how it differs from similar approaches, and what to watch out for.

- What it is: A skill bundle that gives agents web platform knowledge, best practices and browser compatibility data. The skill itself tells the agent to call the modern-web-guidance CLI, and the CLI returns the guide content
- How it works: The agent finds guides with search, fetches one by ID with retrieve, and then writes code. Search runs locally with no API key or network call (per the README)
- Getting it: npx modern-web-guidance@latest install. Apache-2.0. It works with any coding agent that supports skills; Chrome's docs list Claude Code, Codex, Gemini CLI, Copilot CLI, Antigravity, Goose, Grok, Kimi Code and others

Per the README, it contains 250 modern web features (CSS and layout 140, HTML and DOM 36, JavaScript and APIs 74) and 203 real-world development use cases. The use-case areas also include accessibility, built-in AI, forms, performance, privacy, PWA, security, WebAssembly and WebMCP.

Coding agents tend to pick patterns that are common in their training data. Even when the browser now ships a feature natively, they may build it with JavaScript state management or a library. A freeCodeCamp walkthrough (dated June 24, 2026) shows a prompt asking for a tooltip that appears when hovering a button. Without the guidance, the agent wrote a JavaScript state layer with a js-hidden class, a function that dismisses all tooltips, touch handlers and click-outside detection. With the guidance, the output needed no JavaScript and used popover="hint", the interestfor attribute, CSS Anchor Positioning and @starting-style.

A LogRocket article (dated July 22, 2026) compares two copies of the same Next.js task-manager project built with Gemini CLI, with and without the skill. The results are below. It is one run by one author, so it should not be generalized.

According to Chrome's documentation, the flow is as follows. The agent activates the skill for a web task, uses the CLI's search to find guides close to the prompt, fetches the body with retrieve and a guide ID, and writes code according to it. Guides are selected by ID based on their descriptions. The README says search combines an offline, zero-dependency embedding model with a BM25 engine. Guides are written to be token-efficient, and evals are used to prune content that models already know.

The other key idea is the Baseline target. Baseline expresses browser feature support in tiers, and the documentation describes three.

You tell the agent the project's target in AGENTS.md or CLAUDE.md. The official example is "This project's Baseline target is Baseline 2024." With no setting, the default is Widely available. For features outside the target, guides provide fallbacks, usually progressive enhancement, and polyfills are loaded conditionally.

Experimental features are gated as well. "Volatile" features implemented in only one browser engine and Origin Trial features show up in search but cannot be retrieved by default, so the agent does not adopt unstable APIs on its own. To allow them, write a setting in .mwgrc in the project root (or ~/.mwgrc at user level).

The recommended route is the interactive installer. It detects your agent, lets you choose project-level or global installation, and places the skill. The official docs say installing through the CLI enables automatic updates, while most other methods do not update automatically. That Node.js and npm are required is our inference from the use of npx; the official page does not state it.

Per-agent commands from the official documentation (excerpt):

Copilot CLI uses the same /plugin marketplace add form as Claude Code, and Grok, Kimi Code, JetBrains WebStorm and the Antigravity app each have their own steps. After installing in Claude Code, check that the skill file appears under .claude/skills/ in the project root (per the freeCodeCamp steps).

After installation, just ask for things as usual, such as "build a tooltip" or "build a modal." If the agent judges the task to be web-related, the skill kicks in. First, add one line to AGENTS.md (or CLAUDE.md for Claude Code) to set the Baseline target, which decides the range of features the agent may propose.

You can check what the agent receives yourself. search and retrieve work even before installation.

The official documentation groups use into four categories: building new user experiences (accordions, tab bars, container-query dashboards), modernizing legacy code (modals to <dialog>, tooltips to the Popover API), improving security (passkey login, a starter Content Security Policy, security audits) and improving performance (preloading on hover, improving INP and LCP). For an existing project, a workable flow is to find candidates with legacy-scan and then ask the agent to modernize them. Note that the README does not explain how legacy-scan detects patterns or what its output looks like, so you need to judge from the output.

There are other ways to give agents current information: MCP servers that fetch library documentation (such as Context7), MCP servers that query MDN, rules in AGENTS.md or CLAUDE.md, and linters such as ESLint. Modern Web Guidance is distinctive in covering the whole web platform with hand-curated guides delivered together with Baseline support data.

A related tool in a different area is the Hallmark guide, a skill for avoiding generic AI-looking UI design. Hallmark supplies visual direction, while Modern Web Guidance supplies which web standards to implement with. They do different jobs, so using both is conceivable.

According to Chrome's documentation, each use case has evals. Playwright scripts check whether details of a guide were followed, such as @media (prefers-reduced-motion: reduce). A reference implementation must pass 100% and a deliberately flawed one must score 0%, and a generator retries until both hold. End-to-end evals comparing an unguided control with a run using Modern Web Guidance run several times a week with current models and agents. Early results show an average 37 percentage point improvement in adherence to modern best practices. The same page adds that results may vary by project, model, prompts and tools, and we could not confirm the methodology in detail.

The LogRocket and freeCodeCamp articles raise these cautions.

- Chrome describes it as an early preview, so it changes quickly
- It favors newer Baseline features, so unfamiliar APIs appear and browser support must be checked. That may suit a Chrome-only internal app but needs care for a broad public site
- interestfor (the Interest Invokers API) is behind a flag in Chrome and has a polyfill. CSS Anchor Positioning is described as Baseline 2025
- Where mature accessibility components or cross-framework support is needed, a library may still be the better choice
- Moving inline styles or keyframes into global CSS can leave orphaned CSS when a component is removed, so class names need namespacing
- Reviewing generated code (keyboard, focus, screen readers, fallbacks) is still required

- npx ...@latest fetches the latest version from npm on each run. For company use, pin a version or review what gets installed first
- The README says search is offline and needs no network call, but we found no statement about telemetry. In strict environments, check network traffic yourself
- Like AGENTS.md or CLAUDE.md, a skill is a file that changes agent behavior. Check where it is placed and what it contains before installing
- The official page does not describe uninstalling. You would delete the placed skill files such as .claude/skills/ or remove it with each agent's plugin management command