← All articles

Modern Web Guidance: setup, browser targets and safer AI refactoring

Set up Google's Modern Web Guidance for AI coding agents. Learn installation, Baseline browser targets, legacy scans, useful prompts and verification.

Modern Web Guidance gives AI coding agents current web-platform guidance and browser-compatibility context. Use it to research an implementation, set the browsers your project must support, and review older frontend patterns before changing them. Then verify the result in the actual application.

Google’s official documentation presents it as agent skills covering subjects such as HTML, CSS, performance, accessibility and security. This is a practical setup guide based on those primary sources, reviewed on November 17, 2026. It is not a claim that every command below was run against a client website or that FindMilan measured the advertised benchmark results.

What Modern Web Guidance does

An AI coding agent can produce working-looking code while missing a simpler browser feature or the fallback needed by older browsers. Modern Web Guidance helps the agent find relevant implementation advice before it edits files.

The 1.0 materials describe an expanded guide catalog and a modernization workflow for existing code. The useful distinction is between guidance, which informs a change, and verification, which establishes whether that change works in your project. Google’s 1.0 overview explains the release and its evaluation work.

For a business website, I would evaluate it on a real interaction: a contact form, a product filter, a dialog or a mobile navigation component. That makes the intended improvement easier to judge than a request to “modernize everything.”

Step 1: choose the project and installation route

Start in the repository you intend to work on. Save a clean checkpoint or identify existing changes so you can review what the installation adds. Google’s getting-started guide recommends:

npx modern-web-guidance@latest install

The documented installer supports automatic updates. Review its choices rather than assuming every agent needs a separate installation.

For Codex, Google also documents this alternative:

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

For Claude Code, the documented alternative is:

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

Choose one appropriate route. These are instructions for your development environment, not commands to run on a public production server. Check the linked installation page if your agent’s command syntax or plugin support differs.

Step 2: tell the agent which browsers matter

A feature working in the newest Chrome release is not enough if your customers use other engines or older devices. Modern Web Guidance uses Baseline compatibility information; Google’s documentation says the default target is Baseline Widely available when a project does not specify one.

Write a browser policy that reflects the actual audience. Here is an original starting prompt to adapt:

Use Modern Web Guidance for this frontend task.
Before editing, read our existing browser-support policy.
If it is missing, propose a target and explain the trade-offs.
Preserve our design system and current working behavior.
Identify features needing a fallback and explain how to test it.
Do not enable experimental features without discussing the need.

Once agreed, record the policy with the project’s existing instructions. Avoid adding a second, conflicting policy elsewhere.

Google’s cross-browser explanation distinguishes widely available, newly available and limited-availability features. Depending on the feature, a safe implementation may use progressive enhancement, CSS feature detection, a small JavaScript fallback or a conditionally loaded polyfill.

My recommendation is to choose the target from user needs and support commitments, rather than picking a Baseline year because it looks recent. Test both the modern path and the fallback path where your browser policy requires them.

Step 3: confirm the agent is retrieving relevant guidance

A successful installation is not evidence that the agent used it. For a small task, request a relevant guide and inspect the implementation plan.

You can explore the catalog using documented CLI commands:

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

The first command finds candidate guides; the second retrieves a specific guide by ID. For another task, choose an ID returned by your own search. Do not assume this dialog guide is appropriate for every overlay.

If the agent ignores the skill, Google’s troubleshooting page recommends explicitly naming Modern Web Guidance in the prompt. Check which search terms and retrieved guides it used. Ask it to identify gaps rather than invent missing API details.

Step 4: scan a bounded area of an existing site

For older code, Google’s modernization workflow documents local scanning followed by contextual review and verified refactoring. A folder-level scan can be requested with:

npx modern-web-guidance@latest legacy-scan src/components --json

Change the path to match your repository. The scanner covers a subset of patterns that can be detected deterministically; an empty report does not mean the application has no accessibility, security or performance problems.

Ask for a reviewable plan first:

Use Modern Web Guidance to inspect src/components for legacy patterns.
Verify each finding against the surrounding code and our browser policy.
Report the file, behavior, proposed change and regression checks.
Preserve intentional fallbacks and the existing visual design.
Propose one small refactor before editing files.

The documented workflow does not offer a blanket --fix switch. The agent needs to distinguish a genuine modernization opportunity from code that intentionally supports an important use case.

Step 5: test what the user can actually do

I would approve a refactor only after checking the original interaction and its replacement under comparable conditions. Useful acceptance criteria include:

Area What to verify
Forms Labels, validation timing, autofill and a successful permitted submission path
Dialogs and menus Keyboard access, focus movement, dismissal and return to the trigger
Responsive layout Narrow and wide views, zoom, readable text and no unintended clipping
Browser support Native behavior and any required fallback in the relevant engines
Performance Comparable before-and-after measurements on the affected journey

Modern Web Guidance and Chrome DevTools for agents serve different roles: one supplies implementation guidance, while browser tooling helps inspect runtime behavior. Google’s documentation recommends pairing them for a build-and-verify loop. Use your existing test suite alongside browser checks.

A passing build cannot establish that a visitor can complete a checkout or use a dialog with a keyboard. Equally, one fast local performance run is not a promise about every customer’s experience.

What the published benchmarks do and do not tell you

Google publishes evaluation results for its guidance. Those results concern the tested models, prompts and checks. They are useful evidence about the tool’s intended value, but they are not a forecast of your conversion rate, search position or development savings.

I would measure a project’s outcome directly: less unnecessary code, preserved functionality, fewer review corrections, or a demonstrated improvement in the affected interaction. Do not remove a dependency merely because a scanner names a newer alternative. Confirm why the dependency exists and what behavior would be lost.

Where Milan can help

If you want to improve an existing business website, I can help choose a bounded area, review browser requirements and turn the findings into a staged implementation plan through website development. For a larger refresh, start with my website redesign checklist.

If the main issue is how your team uses coding agents, see AI consulting and the Codex instruction-audit guide. My project portfolio shows software-delivery context; this article does not claim a completed Modern Web Guidance client rollout.

The first deliverable should be clear: one interaction, a proposed change and evidence that the finished result still serves the people using the site.

Frequently asked questions

What is Modern Web Guidance?

Modern Web Guidance is Google’s collection of skills and guides that helps compatible AI coding agents use modern web features, implementation practices and browser compatibility information. It does not replace application testing.

How do I install Modern Web Guidance?

Google recommends npx modern-web-guidance@latest install. Run it in the intended project and review the installation choices. Agent-specific alternatives are documented for Codex, Claude Code and other tools; choose one route.

Does legacy-scan automatically fix every issue?

No. It detects a subset of legacy patterns. The agent must review findings in context before proposing or applying a refactor, and the documented workflow has no automatic fix option.

Does it guarantee accessibility, SEO or browser compatibility?

No. Guidance can improve implementation choices, but the finished page still needs browser, keyboard, accessibility and performance checks. It does not guarantee search rankings or a universal compatibility result.

FAQ

Frequently asked questions

What is Modern Web Guidance?

Modern Web Guidance is Google's collection of skills and guides that helps compatible AI coding agents use modern web features, implementation practices and browser compatibility information. It does not replace application testing.

How do I install Modern Web Guidance?

Google recommends npx modern-web-guidance@latest install. Run it in the intended project and review the installation choices. Agent-specific alternatives are documented for Codex, Claude Code and other tools; choose one route.

Does legacy-scan automatically fix every issue?

No. It detects a subset of legacy patterns. The agent must review findings in context before proposing or applying a refactor, and the documented workflow has no automatic fix option.

Does it guarantee accessibility, SEO or browser compatibility?

No. Guidance can improve implementation choices, but the finished page still needs browser, keyboard, accessibility and performance checks. It does not guarantee search rankings or a universal compatibility result.

Need help with Website development and modernization?

Turn the idea into a working system.