GoogleChrome/modern-web-guidance · 17 Nov 2026 · Feature

The Browser Vendors Are Now Writing Docs for Machines

Modern Web Guidance injects Chrome-team expertise into coding agents because LLMs keep shipping 2019's web platform.

GoogleChrome/modern-web-guidance
★24.6k stars Velocity · 7d +1306 ★/day ↘cooling
star history

There is a specific, quietly embarrassing failure mode in AI-generated front-end code: the model cheerfully builds a modal from divs and ARIA roles when a native dialog element exists, wires up resize listeners to position a tooltip that CSS anchor positioning now handles, or writes three hundred lines of JavaScript to accomplish what a dozen lines of modern CSS will do. The code works. It passes review, sometimes. It is simply code from a different decade.

GoogleChrome/modern-web-guidance

This is the gap Modern Web Guidance, a Google Chrome project supported by the Microsoft Edge team and the broader web development community, was built to close. Previewed at Google I/O on May 19 and now shipping as a version 1.0 with input from Mozilla and Microsoft, it is a set of skills that embed web platform expertise, best practices, and live browser compatibility data directly into coding agents. The premise is blunt: LLM training data contains vastly more legacy code than modern code, so agents default to legacy patterns. The fix is not better models. The fix is better context.

The model isn’t stupid, it’s statistical

The most useful framing of the problem comes from a third-party review of the project: the model is “being statistical,” not stupid. There is simply far more code on the internet using 2019 patterns than 2026 patterns, and a language model trained on that corpus will reproduce the distribution. Even when a model knows a modern API exists, it often lacks the density of real-world implementation detail — the gotchas, the fallbacks, the production-ready structure — needed to use it correctly.

This is a broader phenomenon than the web platform. The Stack Overflow blog recently argued that guidelines written for agents must be more explicit and demonstrative than those written for humans, because agents don’t run on vibes — the tacit, experience-based knowledge a senior engineer brings to code review doesn’t transfer to a statistical system unless someone writes it down. Heroku’s chief architect made the same point: principles like DRY that seasoned engineers take for granted must be explicitly prompted in LLMs, or the model “will do whatever it wants.”

Modern Web Guidance is that principle applied to an entire platform, written by the people who build the platform. The guides are authored and reviewed by Chrome subject-matter experts, including contributors from outside big tech, and they’re practical rather than reference-style: how to build a navigation drawer, how to animate to and from the top layer, where the 64KB payload quota on fetchLater() will bite you, which macOS scrollbar behaviors will surprise you.

Retrieval, not fine-tuning

Architecturally, the project is refreshingly unglamorous. There is no intermediary service, no API key, no network dependency. When an agent activates the skill, it’s instructed to call a local CLI that performs semantic search over the guide library and returns a ranked shortlist with similarity scores and token counts; the agent then retrieves the winning guide and its patterns land directly in the context window. The search runs on an offline, CPU-efficient TensorFlow.js model. According to the Chrome documentation, the local vector index was at one point a 507 MB artifact before being reduced to what the docs describe, somewhat cryptically, as a 7-line loop — the phrasing suggests an aggressive simplification, though the exact engineering is left unclear. Either way, retrieval happens in milliseconds on the developer’s machine.

The token discipline is the part that deserves attention, because it’s where most context-injection schemes die. The skill’s resident footprint is tiny — the core pack costs roughly 234 tokens, a Chrome extensions pack about 181 — and the guides themselves are deliberately pruned. The team runs evals to identify lowest-common-denominator content that models already know and cuts it. In other words, they’re not just curating what to teach agents; they’re curating what not to, on empirical grounds. That’s a genuinely different editorial posture from documentation written for humans, where redundancy is harmless.

The compatibility story is similarly concrete. The project consumes live Baseline data — the cross-browser feature-support standard — combined with a project’s stated browser targets, and generates progressive enhancement strategies, @supports queries, or polyfills accordingly. The fallback philosophy is opinionated: purely additive enhancements like speculative preloading are safe to let older browsers silently ignore, while critical behaviors get lightweight, case-specific fallbacks under 50 lines of code, rather than heavy third-party polyfill bundles. The guides explicitly distinguish between the two categories, which is the kind of judgment call that’s hard to extract from training data and easy to write down.

The eval harness is the real product

What separates Modern Web Guidance from a well-organized docs folder is the closed-loop validation pipeline. The team defines simulated developer tasks phrased the way real developers phrase things — “make my images load faster” — deliberately avoiding naming any API, so the eval tests whether the agent can discover the right guide on its own. Browser automation scripts then verify the generated code against exact runtime behaviors, computed styles, and accessibility states. Graders are calibrated against both a gold-standard implementation (must pass 100%) and a deliberately wrong negative demo (must fail 100%), with automatic refinement when tests misfire.

The headline numbers: on a public evaluation dashboard, unguided frontier models pass roughly 51% of modern web checks, versus 91% with the guidance attached. The README’s own results table shows consistent uplifts across three agent families — Codex CLI, Claude Code, and Google’s Antigravity — ranging from +22 to +34 percentage points on 130-task suites with over a thousand assertions each. Claude Code with Opus moved from 58% to 92%. Notably, the team publishes the concept of “opportunity” — 100% minus the unguided pass rate — and openly states that where models already do well, the guidance adds little. That’s an unusual degree of honesty for a vendor tool; most would prefer you not see the tasks where their product doesn’t help.

Who’s actually using it

The adoption evidence is more concrete than most preview-stage projects can claim. Policybazaar and Pensionbazaar reported cutting new page turnaround and UI bugs by over 90% and reducing manual Core Web Vitals auditing effort by 92%. MetaMask deployed a three-line advisory PR review bot built on the guidance across roughly 480 pull requests, driving 43 accessibility and semantic HTML fixes with a 15-minute median turnaround — a use case the project’s creators probably didn’t anticipate, which is usually a sign of something real. WeTV automatically diagnosed and fixed 90% of recurring layout-shift regressions in CI/CD; note inc. raised modern web guideline adherence from 61% to 94%. These are vendor-published case studies, so the usual discount applies, but the MetaMask example in particular is independently verifiable in principle and structurally plausible.

One skill in a growing stack

Modern Web Guidance lands in the middle of a rapidly formalizing ecosystem of machine-facing documentation. AGENTS.md, which moved to the Agentic AI Foundation under the Linux Foundation, now appears in over 60,000 repositories and provides a modest accuracy boost to coding agents — but only when humans maintain it. llms.txt serves answer engines rather than coding agents. SKILL.md files define reusable workflows inside skill directories, which is the slot Modern Web Guidance occupies. Next.js bundles version-matched documentation inside the package itself and generates an AGENTS.md for new projects, instructing agents to read the bundled docs before coding rather than trusting frozen training data.

The pattern across all of them is the same insight: training data has a cutoff, and the antidote is just-in-time, version-matched, machine-legible documentation. Modern Web Guidance is the most ambitious expression of that idea because it isn’t documenting one framework — it’s documenting an entire platform, with live compatibility data, on behalf of multiple browser vendors. A practitioner workflow writeup from the Angular world makes the complementary point: the AGENTS.md file carrying project guidelines has become the standard contract between developer and agent, and the developer remains the team leader while the AI acts as domestique. Modern Web Guidance slots into exactly that division of labor — it handles platform knowledge so the human can handle judgment.

The rough edges

The project is a preview, and it has visible seams. The guide count is inconsistent across sources: the README says 103 features across 131 use cases, while the Chrome documentation says 200+ guides — likely different ways of counting guides versus features versus use cases, but the discrepancy is unresolved in the sources. The published repo is purely a distribution target; development happens in a separate source repository, which is fine hygiene but means the GitHub stars land on a repo that’s essentially a build artifact.

Then there’s telemetry. The README pitches the CLI as offline, private, and local — and the search genuinely is — but Google collects anonymous usage information including installation counts, guide retrieval IDs, and the agent-generated search queries. Raw user prompts are excluded, the collection code is inspectable, and an opt-out environment variable exists. Still, “completely private and local” and “Google collects your search queries” coexist awkwardly in the same README, and developers are right to read both sentences carefully.

The independent review flagged a deeper set of criticisms that the community is still arguing about: data retention terms, licensing of the derived content (portions come from MDN and W3C/WHATWG/IETF specifications), and the complaint that adopting the tool means “doing Google’s work for free” — letting a browser vendor’s priorities shape what agents build, at zero cost to Google. The reviewer promised to address these in depth; the sources here don’t record the resolution, so the debate should be treated as live. There’s also a fair structural question about whether guidance this good being vendor-authored creates a soft channel for platform advocacy — though the Edge team’s involvement and the Baseline-based, cross-browser compatibility data cut against the strongest version of that critique.

The boring part is the point

Strip away the eval dashboards and the case studies, and Modern Web Guidance is a curated, token-efficient, locally-indexed corpus of expert knowledge, delivered into a context window at the moment of need. That’s not a glamorous architecture. It’s also, arguably, the correct one: fine-tuning platform knowledge into models would go stale on the same schedule as training data, while a retrieval corpus updates with the platform itself and can be pruned against what models already know.

The larger signal is about who documentation is now for. For twenty years, browser vendors wrote docs for humans, and humans read a shrinking fraction of them. Now the primary reader of web platform documentation may be an agent — and agents read everything, follow instructions literally, and measurably improve when the material is good. The Chrome team has simply been the first to take that reader seriously enough to build an eval harness around it. The interesting question isn’t whether other platform vendors follow. It’s whether the humans reviewing the output start reading these guides too, on the theory that if it’s good enough to fix the agents, it might be good enough to fix us.

Sources

  1. Modern Web Guidance | Chrome for Developers
  2. 5 Concepts to Know for Coding with AI Agents
  3. llms.txt vs agents.md: 2026 Guide for Brands
  4. Building apps with AI agents - 10 tips from 9 months of coding
  5. Llms.txt and agents.md
  6. Modern Web Guidance in your AI workflow
  7. Building shared coding guidelines for AI (and people too)
  8. A Guide to llms.txt, AGENTS.md, SKILL.md, and MCP
  9. Modern Web Guidance as a starting point for my own token ...
  10. Keep Agentic AI Simple: A Practical Workflow for Software ...
  11. AGENTS.md and llms.txt: Making Your Next.js Project ...
  12. Get started with Modern Web Guidance - Chrome for Developers

heatdrop uses Google Analytics to see which pages get read — nothing else. Your call. How we handle data.