跪拜 Guibai
← Back to the summary

Chrome's Modern Web Guidance 1.0, Torn Open: 0.77s Offline Retrieval, a Scanner Blind to Most Legacy Code, Telemetry On by Default

There's an interesting trend on Juejin's hot list lately: enterprise official repos are landing in batches, almost all carrying spec files written for AI coding assistants. One roundup counts 32 hot-list slots for such repos in the past week alone. The loudest of these is Chrome's Modern Web Guidance — it hit 1.0 on November 10, and Edge, Firefox, and MDN teams are also on the maintainer list. That's effectively all four browser camps agreeing on "how AI should write frontend code."

I've had a nagging question about this kind of spec package: what is it actually made of? The marketing copy is all similar — "pack modern web best practices into your coding agent" — which sounds like a nicely decorated prompt collection. What determines its value is the details: is the guide content documentation or instructions? Is the retrieval a gimmick or real infrastructure? Can the scanner actually recognize old code? Hot-list articles all stop at describing trends; nobody opens it up. Since this thing runs with a single npx command, I tore it apart and tested it.

What's in the package

Check the size first: the npm package is 16.5MB, version 1.0.0. After installing (npx caches it locally) and flipping through the directory, the structure is simpler than I expected:

modern-web-guidance/
├── skills/modern-web-guidance/
│   ├── SKILL.md            # instructions for agents
│   ├── modern-web.mjs      # main CLI entry
│   ├── legacy-scan.mjs     # scanner, 5MB
│   └── gen/                # offline semantic retrieval index
│       ├── guide-chunks.i8     # int8-quantized guide vectors
│       └── query-words.i8      # 7.4MB query vocabulary
└── policies/

The gen/ directory is the key. The "local offline semantic search" is not marketing talk: it builds the guide content into an int8-quantized embedding index packed directly into the package, and retrieval never touches the network. I cross-checked against the source repo (modern-web-guidance-src): the repo has 252 guide.md files and 51 rule files, but the npm package only ships 35 rules spread across 33 guides. In other words, the officially claimed 203 use-case guides are the release-line figure; the source is ahead of the release. Rules like structured-clone (teaching you to replace JSON.parse(JSON.stringify()) with structuredClone), a pure JS rule, exist in the repo but not in the package. This gap caused other issues later; setting that aside for now.

Retrieval: 0.77 seconds, content shaped like "guarded instructions"

Retrieval is the core workflow of this thing. Before writing frontend code, the agent calls search to get IDs of relevant guides, then retrieve to pull full text. I tried the most common scenario:

$ npx modern-web-guidance@latest search "light dismiss dialog"
[{"id":"light-dismiss-a-dialog","description":"Create a modal dialog that can be closed via light dismiss..."},
 {"id":"platform-controls-dismiss-dialog",...},
 {"id":"dialog",...},
 ...10 results total]

Searching "close dialog by clicking outside", the first result it returns is indeed correct, and the ordering makes sense. With the ID, retrieve:

$ npx modern-web-guidance@latest retrieve "light-dismiss-a-dialog"

This command runs to completion in 0.77 seconds — including npx package parsing time. The output guide looks like this: the usage of the closedby="any" attribute, followed by a set of hard instructions: MANDATORY use showModal() to open, DO NOT use closedby on non-modal dialogs, plus one saying "don't hang critical logic on click events; listen for close or cancel instead." What surprised me most was the fallback strategy section:

Browser support for <dialog closedby>: Limited availability. Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).

Exact to version numbers and months, and Safari is not listed — meaning Safari hasn't caught up. This is not how human-facing documentation is written; these are hard boundaries drawn for agents: what's usable, what's off-limits, what to fall back on, all on one page. Calling it "guarded instructions" is more accurate; the agent can execute it directly without having to go check compatibility itself.

I flipped through several other guides, and the format is consistent: frontmatter declares which web-feature-ids it depends on and which other guides it cross-references, and the body is all action directives plus fallbacks. The quality is better than I expected.

More interesting than the guide content is SKILL.md — that instruction manual for agents is itself a working procedure. It dictates how the agent should search: queries must be 2 to 5 words, action-oriented, with framework names like React or Vue banned; user intents like "show a confirmation dialog before deleting" must first be translated to "confirmation modal dialog" before searching; multi-function compound requirements must be split into two searches. The opening also sets a hard trigger condition: all HTML/CSS and client-side JS tasks must run this skill first with "Do NOT skip", while backend, CI/CD, and Docker tasks are explicitly forbidden from triggering it. Seeing this, I realized this thing is not a reference book for agents; it's a checkpoint inserted into the agent's workflow.

Scanner: first round 0 hits, where's the problem

What really took my time is legacy-scan, the new modernization scanner: it scans your existing project, finds old patterns, and maps them to corresponding guides. The README example looks appealing: scanning etherpad-lite reports missing autocomplete, and that ::-webkit-scrollbar should be replaced with scrollbar-color. I first fed it a piece of "2015-flavored" code I wrote myself — manually building a modal with createElement, a hover-to-show tooltip, JSON.parse(JSON.stringify()) deep copy, requestAnimationFrame hand-written animation, all old code AI loves to generate.

Result: 0 hits.

Modern Web Guidance Analyzer — .
0 findings from 33 qualified guides.
Note: legacy-scan covers legacy patterns for 33 guides (~20% of the guidance corpus).

At first I thought the scanner was broken. Unwilling to give up, I went back and read the rule source, and found the trick when I got to the scrollbar rule — it has a file-level guard:

// 1. If stylesheet already defines standard scrollbar properties, skip
if (
  ctx.stylesheetHasProperty('scrollbar-width') ||
  ctx.stylesheetHasProperty('scrollbar-color')
) { return; }

As soon as a standard scrollbar-width or scrollbar-color appears anywhere in the stylesheet, all hits for ::-webkit-scrollbar in that file are dropped. The logic: if you've already written the standard properties, those vendor prefixes are probably intentional fallbacks, and reporting them would be a false positive. My test file happened to have a line .sidebar { scrollbar-width: thin; }, which suppressed all hits in the whole file. Splitting the vendor prefix into a separate file and scanning again, the same pattern immediately reports 2 hits.

With the guard logic understood, the first round's 0 hits mostly makes sense: the scanner runs deterministic rule matching (TypeScript AST, CSS parsing, package.json dependencies), and each of the 35 rules is written extremely narrow — the deep-copy rule, for example, carries a long exclusion list of "non-cloneable objects" (localStorage, Vue's reactive return values, AbortController... all get skipped). Rules would rather have nothing than a false positive, and my demo code happened to not land in the narrow gaps. I constructed a second test project precisely per the rules, and both hits landed on the point:

* autofill-sign-in-form (1 finding)
  Password input in sign-in or credential form should specify
  autocomplete="current-password" or autocomplete="new-password".
  - signin.html:3
    <input type="password" name="password">

* form-fields-automatically-fit-contents (1 finding)
  Imperative JavaScript auto-resizing of textareas and inputs using
  scrollHeight or autosize() should be replaced with CSS field-sizing: content.
  - app.js:5
    ta.style.height = ta.scrollHeight + 'px';

I agree with both of these: password fields in forms have lacked autocomplete for ages, and manually calculating scrollHeight for textareas should indeed become field-sizing: content. Each hit also carries keepWhen/dropWhen verification criteria so the agent (or a human) can double-check, not just report on seeing a pattern.

But this also exposes its ceiling: 35 rules only cover about 20% of the guidance corpus. The remaining 80% of scenarios it doesn't even look at — my demo's manual modal and hand-written animation have no corresponding entry in the rule list. The official docs also state it plainly: legacy-scan only checks the subset with deterministic rules; the rest relies on the agent's own search. If you use it as a checkup tool, keep expectations low: what it reports is precisely sliced, and what it doesn't report doesn't mean there's no problem.

While reading the rule docs I also noticed a detail that made me warm to it: format-support.md includes a discipline — for supported scan formats, "0 findings cannot silently mean not checked". Parsing failures must be visibly reported, not quietly counted as 0 hits. The comments also admit the skip-tracking code is "still being wired up", not finished yet. If that first 0 hits was caused by a parsing failure, with the current version I'd have no way to tell the difference. This practice of writing unfinished work in the open is far more credible than a README of uniform selling points.

The source-vs-release gap mentioned earlier bites here too: the structured-clone rule in the repo can recognize JSON.parse(JSON.stringify()), but it's not in the published package, so my deep-copy legacy code is invisible to it. This tool iterates fast and the rule list will catch up; it's just that at this point in time, the source repo and the npm package are two different versions of the story.

"Fully offline" is real; privacy is DIY

While unpacking, I also glanced at the telemetry implementation and found a spot where the README doesn't align. The Quickstart section says the CLI "works offline, completely private and local", but the Telemetry section admits: by default it collects install counts, agent names, guide retrieval IDs, and "agent-generated search queries".

The code is explicit: isTelemetryEnabled() returns true by default, and only setting DISABLE_TELEMETRY=1 turns it off. What gets sent includes raw search query text, matched guide IDs, agent names detected via environment variables (it has dedicated detection logic for Claude Code, Codex, Devin), OS, and latency buckets. In other words, retrieval itself is offline and needs no API key, but every search your agent makes sends one record back to Google's clearcut endpoint by default. One piece of advice if you use it: add export DISABLE_TELEMETRY=1 to your shell config before wiring it in, especially in enterprise environments.

Where this thing sits

After running through all of this, my judgment: its value is not in the scanner — that's a narrow tool that only recognizes about two in ten scenarios — but in the 203 guides themselves. Fallbacks precise to browser version numbers, instructions guarded with keepWhen/dropWhen, and every guide has evaluation data (Google's published figures say agents with the guides go from about 50% pass rate to about 90%; Japan's note company reports 61% to 94%. The numbers look nice, but I can't reproduce their evaluations on my machine, so I treat them with skepticism). The decade-old code in model weights isn't going to disappear, so hang an expiring common-sense layer on the outside, with version numbers tracking Baseline. The cost of hanging it on is near zero: one npx command, and retrieval costs nothing. Treat the scanner as a narrow-gauge checkup table; verify each hit it reports, and keep in mind that what it doesn't report is on you. Oh, and don't forget that environment variable.