Modern Web Guidance

Modern Web Guidance is a set of skills that embed web platform expertise, best practices, and browser compatibility data directly into your coding agents. It helps to steer your coding agents away from legacy patterns, and instead toward solutions that harness the power and capabilities of the modern web platform.

Stewarded by the Google Chrome, Microsoft Edge, Mozilla Firefox, and MDN teams, alongside the web development community.

Documentation · Eval Dashboard · Source Code · Report an Issue

Quickstart

npx modern-web-guidance@latest install

This command runs an interactive wizard to install Modern Web Guidance. 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"

# 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

View an example: the navigation-drawer guide.

The full list

CSS & Layout (140 features)

::backdrop	content-visibility	progress()
::details-content	contrast-color()	reading-flow
::file-selector-button	Cross-document view transitions	Relative colors
::placeholder	currentColor	rem
::selection

HTML & DOM (36 features)

:autofill	<slot>	HTML streaming setters
:indeterminate	<video>	HTML-in-canvas
<audio>	Autonomous custom elements	inert
<details>	blocking="render"	Interest invokers
<dialog closedby>

JavaScript & APIs (74 features)

<install>	integrity() for url()	Sanitizer API
<meta name="text-scale">	Interaction contentful paint performance entries	Scheduler API
<template for>	Intersection observer	Small, large, and dynamic viewport units
AbortController and AbortSignal	Intl.DurationFormat	Soft navigation performance entries

• accessible-error-announcement: Synchronize programmatic accessibility states (like aria-invalid) with the visual :user-invalid state to ensure screen reader users receive error feedback only after interaction, mirroring the visual experience.
• accessible-generated-content: Use CSS generated content (::before/::after) in ways that stay accessible, including alternative text for decorative content.
• respect-os-text-scale: Respect the operating system's text scale preference for a page so font sizes, layout, and rem-based measurements follow the user's accessibility settings.

• language-detection: Detect the language of user-generated content or already present site content.
• language-model: Run on-device natural language inference in the browser using the Prompt API, with streaming output, structured JSON responses, and multi-turn session management.
• summarizer: Summarize text content using the on-device Summarizer API.
• translator: Translate text between languages using the on-device Translator API.

• animate-to-intrinsic-sizes: Smoothly animate interactive components (like accordions, menus, and expanding cards) to and from their natural dimensions.
• atrule-support-conditionals: Conditionally apply certain CSS rules or declarations only if a certain at-rule is supported by the browser.
• calculate-with-intrinsic-sizes: Calculate the size of an element based on its intrinsic size, while ensuring it fits within given design constraints.
• child-state-based-styling: Build a component that changes its styling based on the state of one of its child elements. For example, a component that renders in light or dark mode based on whether a theme toggle is checked (or not).
• content-based-styling: Build a component that changes its layout based on whether it contains specific child elements (or not). For example, if the component contains an image, use a multi-column layout, otherwise default to a single-column layout.
• css: Action-oriented guidelines for modern CSS architecture, including the cascade, selectors, scoping, nesting, and design tokens. Use this guide when authoring styles or managing design systems.
• css-layout: Modern CSS layouts such as flexbox, grid, subgrid, container queries, anchor positioning, and intrinsic sizing. Use this skill when architecting responsive UI components or page layouts.

• animated-select-picker: Create a custom select component whose dropdown is animated. For example, the menu fades or slides into view, or the options animate upon selection.
• autofill-address-form: Build an address form with correct autocomplete attributes and autofill support.
• autofill-highlight-inputs: Customize the styling of form fields that have been autofilled and not edited by the user
• autofill-payment-form: Build a payment form that collects card details with correct autocomplete values and autofill support.
• autofill-sign-in-form: Build a sign-in form with correct autocomplete values and autofill support.
• autofill-sign-up-form: Build a sign-up form with correct autocomplete values and autofill support.
• brand-consistent-forms: Match checkboxes, radio buttons, range sliders, and progress bars to your site's color palette without replacing them with custom components.
• branded-select-styling: Create custom select elements whose button, picker, arrow icon, and checkmark all seamlessly match your brand or design system's typography, colors, spacing, and border treatments.

• accessible-web-components: Make custom elements accessible by default, setting roles and ARIA state via the ElementInternals ARIA mixin, managing focus with delegatesFocus, and keeping ARIA relationships within a single shadow root.
• custom-elements: Define, register, and manage the lifecycle of autonomous custom elements, covering constructor rules, lifecycle callbacks, upgrade timing, attribute/property reflection, and naming conventions.
• form-associated-custom-elements: Make a custom control participate natively in forms with formAssociated and ElementInternals, submitting its own value, integrating with constraint validation, and reacting to reset, disable, and state-restore.
• prerendering-custom-elements: Server-render a custom element, then hydrate it in place without re-rendering or a flash of unstyled content.
• shadow-dom: Encapsulate a component's DOM and styles with Shadow DOM, construct the tree efficiently with HTML templates, and project consumer content with slots.
• styling-web-components: Style across the shadow boundary with :host selectors, inherited and custom properties for theming, ::slotted and ::part, and cascade layers and container queries inside components.
• web-components: Orientation and cross-cutting principles for authoring and using Web Components, covering Custom Elements, Shadow DOM, templates and slots, Declarative Shadow DOM, styling across the shadow boundary, Form-Associated Custom Elements, and accessibility requirements. Use this guide when building reusable UI components, design systems, or server-rendered custom elements.

• calculate-event-differentials: Calculate elapsed or remaining time between dates and times, balance duration units, and format human-readable localized durations using Temporal.Duration and Intl.DurationFormat.
• capture-location-agnostic-data: Model location-agnostic calendar dates, wall-clock times, partial dates (recurring birthdays, credit card expirations), and recurring monthly intervals without time zone drift using Temporal Plain types.
• coordinate-global-events: Schedule future meetings or events by explicitly binding them to a geographical IANA time zone so that event times remain accurate regardless of Daylight Saving Time (DST) transitions, "skipped" or "repeated" hours during clock changes.
• sort-high-precision-timestamps: Parse, sort, and measure intervals between sub-millisecond or nanosecond ISO 8601 timestamps without Date truncation collisions using Temporal.Instant.
• support-global-calendar-systems: Display and calculate dates in non-Gregorian calendar systems (e.g., Islamic, Hebrew, or Chinese) accurately for international users.

• batch-analytics-events: Debounce and batch multiple analytics, telemetry, and Core Web Vitals events together in a single beacon to minimize network contention and reduce server load, while still delivering real-time updates.
• break-up-long-tasks: Break up heavy synchronous processing (complex computations and/or long loops) or DOM updates to improve Interaction to Next Paint (INP) responsiveness and let the browser handle user input and repaint the screen.
• calculate-total-foreground-time: Calculate the total time a user actually spent viewing a page, excluding periods when the tab was in the background.
• conditional-async-dependencies: Conditionally load or initialize async dependencies (such as importing polyfills for missing web features) without requiring complex orchestration across all of a page's script dependencies.
• defer-rendering-heavy-content: Reduce rendering times in content-heavy web pages (e.g. pages with long feeds, lots of articles, or complex dashboards), by deferring rendering for any content that is not immediately visible to the user.
• defer-work-until-scroll-ends: Defer expensive operations like DOM updates, data fetching, analytics tracking, or layout recalculation until after scrolling completes to maintain smooth scroll performance.
• deliver-optimized-decorative-images: Deliver optimized decorative images (such as backgrounds, UI icons, or complex masks) by simultaneously providing next-generation image formats (like AVIF or WebP) alongside multiple pixel densities (like 1x and 2x) so the browser can dynamically negotiate the best combination of file size and visual quality for the user's device capabilities.

• privacy: Action-oriented guidelines for web developers to implement privacy by design, data minimization, third-party audits, and secure data handling. Use this skill when designing applications, integrating third-party services, handling user data, or configuring security headers.

• install-web-app: Install web applications from a page using browser-controlled consent UI.
• migrate-web-app-origin: Transfer an installed web app to a new origin while preserving user configuration and OS-level shortcuts.

• client-side-encryption: Establish shared secrets using public-key encapsulation or key agreement—including hybrid and post-quantum protection—and encrypt sensitive data in the browser with authenticated encryption.
• digital-signatures: Sign and verify messages, tokens, or artifacts in the browser using classical or quantum-resistant (post-quantum) asymmetric keys to ensure data integrity and authenticity.
• local-network-access: Access resources on a user's local network or loopback interface from a public web application.
• passkey-authentication: Authenticate a returning user with a passkey for primary sign-in.
• passkey-conditional-create: Silently register a passkey for an existing user after a successful password login.
• passkey-management: Let users view and manage the passkeys registered to their account.
• passkey-reauthentication: Verify a signed-in user's identity using their existing passkeys before a sensitive action.
• passkey-registration: Register a passkey for an existing user account.

• carousel-slide-effects: Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.
• component-specific-light-dark-theme: Force certain elements to be in light mode or dark mode (e.g. code blocks, media players, etc) independently of the page's color-scheme.
• icons: Display and manage icons that can be set and parameterized from CSS, are fast to load, crisp at any resolution and are properly exposed to (or hidden from) assistive technologies.
• position-aware-tooltips: Build tooltips and popovers with directional arrows (or other visual styling) that automatically point the correct way when the element flips to a fallback position.
• pull-to-reveal: Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.
• responsive-table: Build a data table that presents tabular data with proper header semantics, and remains readable and navigable on small screens and with assistive technologies.
• scroll-position-aware-elements: Build floating buttons or widgets (back-to-top, scroll-to-bottom, chat launchers, etc.) that appear and disappear based on whether the user has scrolled at all.

• 2d-panning: Allow users to freely pan or scroll two-dimensional surfaces—such as maps, zoomed images, infinite canvases, or large data grids—across both directions (whether diagonally or changing direction mid-gesture) without the gesture locking to a single horizontal or vertical axis.
• anchor-positioning-tab-underline: Transition an element seamlessly between two target element positions. For example, moving a selected tab underline between the previously selected tab and the currently selected tab.
• animate-element-entry-exit: Smoothly hide/show elements as they are added/removed from the DOM or as their display values are toggled.
• animate-to-from-top-layer: Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer.
• carousel-snap-highlights: Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden content.
• consistent-cross-document-transitions: Ensure critical page state is loaded and stable before initiating a cross-document view transition. This means critical CSS styles are loaded and applied, critical JavaScript is loaded and run, and the HTML visible for the user's initial view of the page has been parsed before the transition runs.
• cross-document-transitions: Create smooth, seamless transitions between full page navigations, such as cross-fades, custom reveal effects, or morphing of content from one page to the next.

• accordion: Build an accordion component with animation, optional exclusive (one-open-at-a-time) behavior, and brand-consistent styling.
• app-menus: Build an application menu bar where several top-level menus (such as File, Edit, and View) act as a single keyboard stop and switch between each other on hover or arrow keys.
• breadcrumbs: Build a breadcrumb trail that shows the user's location within a site hierarchy and lets them navigate to ancestor pages.
• card: Build a card component that adapts its presentation to its own available space and contents.
• carousel: Build a carousel component that displays a set of items in a horizontal or vertical layout.
• checkbox: Style checkboxes, including custom icons, layout, colors, check/uncheck animations, while preserving native functionality and accessibility.
• copy-button: Build a copy button that copies text from arbitrary elements to the clipboard.
• dark-mode-toggle: Build a dark mode toggle component that allows users to override their system color scheme preference for the current site.

• content-first-noise-reduction: Maximize content and reduce noise by removing blocking popups, keeping persistent navigation compact, and moving secondary content behind on-demand disclosure.
• form-factor-adaptation: Adapt layouts, controls, and text to any device or container so touch targets stay usable, content fits its space, and nothing collides with system UI.
• natural-interactions: Implement natural interactions with clear hover, focus, and press feedback, motion that opens from its trigger, swipeable content, and keyboard-reachable actions.

• adapt-scrollbar-to-contrast-preferences: Enhance scrollbar visibility for users who prefer high-contrast interfaces
• apply-webgl-shaders: Apply custom visual effects with WebGL shaders to HTML content.
• browser-ui-theming: Theme browser-generated UI such as text selection, scrollbars, form controls, and pickers with CSS instead of re-creating it with custom elements.
• color: Color guidance for the web, including contrast requirements, light and dark color schemes, Forced Colors Mode, and generating tints and shades from a base color.
• complex-shapes: Clip elements and their content to any free-form shape, like a symbol, brush stroke, or organic texture for more expressive designs.
• contrast-color: Select a readable text color with sufficient contrast on a dynamic background color.
• custom-text-decorations: Add text decorations such as underlines, overlines, strikethroughs, or entirely custom shapes, with reveal animations, custom offsets and end insets, and flexible ink skipping.
• customize-scrollbar-color-and-thickness: Customize the color or thickness of a scrollbar

• cpp-on-the-web: Compile C/C++ to WebAssembly using Emscripten

• agentic-forms: Expose client-side functionality as tools to AI agents by annotating standard HTML forms with WebMCP attributes.
• agentic-javascript-tools: Programmatically register client-side JavaScript functions as tools for AI agents using the WebMCP Imperative API.
• webmcp: Use this guide to implement WebMCP in browser applications, exposing client-side functionality as tools to AI agents via declarative or imperative APIs.

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 dynamically adapt to current browser support.
• Origin Trial & Volatile Feature Gates: Guides covering experimental Origin Trial APIs or volatile features (single-engine features shipped within the last 3 months or still stabilizing) remain discoverable via search, but are gated on retrieve so agents do not adopt unstable APIs without explicit developer consent.

Project Configuration (.mwgrc)

Configure Origin Trial and volatile feature opt-ins for a repository with an optional .mwgrc JSON file in your project root (or ~/.mwgrc as a user-level fallback), which you can commit to share across your team:

CLI Command	.mwgrc Key	Effect
npx modern-web-guidance@latest set-allow-origin-trials	"allowOriginTrials": true	Unlocks guides for experimental Origin Trial APIs.
npx modern-web-guidance@latest set-allow-volatile-features	"allowVolatileFeatures": true	Unlocks guides for volatile single-engine features.

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 "<query>". The tool matches the query to the best guide using an offline, zero-dependency embedding model and BM25 search engine (no network calls, no API keys).
3. Guide Fetch: The agent retrieves the guide via modern-web-guidance 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

npx skills add GoogleChrome/modern-web-guidance

gh skill install GoogleChrome/modern-web-guidance

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

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

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

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

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

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

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.

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:

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.

[!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

Found a bug, outdated pattern, or missing web platform feature? Open an issue or see CONTRIBUTING.md in the source repository (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.
• 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.