What Modern Web Guidance's legacy scan catches

HTML5 Boilerplate 4.3.0 came out on 10 September 2013. It ships normalize.css, a .clearfix hack, IE conditional comments and jQuery 1.10.2. Run Google Chrome’s new legacy-scan command over it and the answer is:

"totalFindings": 0,
"activeRuleCount": 52,
"activeGuideCount": 38,
"note": "No legacy patterns found across 38 guides (52 rules; ~20% of the guidance corpus). ..."

That is not a bug. It tells you what the scanner is for. legacy-scan does not look for old code in general. It looks for 52 specific hand-rolled UI tricks that a newer CSS or HTML feature now does natively: transitioning max-height to fake an accordion opening, ::-webkit-scrollbar styling, input:invalid error styles that fire before the user has typed anything, border-bottom used as an underline, dark mode written as colour overrides inside @media (prefers-color-scheme: dark), an Enter-key handler that breaks Chinese and Japanese input. If your code has those, it finds them in under a second and points at the guide that replaces them. If it does not, a clean result says nothing about how modern the rest of your code is.

Everything below was run with modern-web-guidance 1.0.1 on Node 22.23.5, in a throwaway node:22-bookworm-slim container with telemetry switched off, on 20 November 2026. The skill was not installed into a coding agent, so what an agent does with the guides was not tested.

What it is

Modern Web Guidance (README checked 20 November 2026) is a set of agent skills plus a CLI. The README describes it as “a set of skills that embed web platform expertise, best practices, and browser compatibility data directly into your coding agents”, and lists the Chrome, Edge, Firefox and MDN teams as stewards. It claims 262 web features and 204 use cases, with compatibility data from the Baseline project. The code is Apache-2.0, the guides are CC-BY 4.0, and it needs Node.js 22 or later.

The idea is that your agent, which learned CSS from years of Stack Overflow answers, asks the CLI for a current guide before it writes a dialog or an accordion. Search runs locally. The README says it uses “an offline, zero-dependency embedding model and BM25 search engine (no search API calls or API keys)”. It also sends anonymous usage telemetry when online. Set DISABLE_TELEMETRY=1 to stop that.

The CLI has three commands that matter here:

npx modern-web-guidance@latest legacy-scan .        # find hacks with a native replacement
npx modern-web-guidance@latest search "<query>"     # find a guide
npx modern-web-guidance@latest retrieve <guide-id>  # print it

According to its --help output, legacy-scan also takes --json for agents, --guide <id> to check one guide, and --include-docs-and-tests (docs, examples, demos and tests are skipped by default).

What it caught

To see the scanner find something, a small fixture went in with six well-known patterns: an accordion transitioning max-height, a .sidebar::-webkit-scrollbar { width: 6px; } rule, input:invalid { border-color: red; }, nav a underlined with border-bottom, a dark-mode block that sets background and color inside prefers-color-scheme, and a search box that submits on event.key === 'Enter'.

Found 5 modernization opportunities across 5 guides (scanned 38 guides with deterministic rules; ~20% of the guidance corpus):
Note: Static analysis results are provisional — verify against the Keep/Drop criteria below.

* animate-to-intrinsic-sizes (1 finding)
  CSS transition on max-height simulates intrinsic size animation; modernize with interpolate-size: allow-keywords or calc-size().
  ...
  - site.css:1
    .accordion-panel {

The other four were custom-text-decorations, dark-mode, ime-safe-enter-submit and validate-input-after-interaction, each with a file and line number. Every finding comes with a “Keep when” and a “Drop when”, so an agent (or you) can throw out false positives. The max-height one, for example, says to drop it when the element is a scroll container with overflow: auto and the max-height is a real limit, not an animation trick.

The scrollbar rule was the one miss. A lone ::-webkit-scrollbar { width: 6px; } was not flagged. Add a ::-webkit-scrollbar-thumb rule and a display: none one next to it, and all three got flagged under customize-scrollbar-color-and-thickness. So it reads a pattern, not single declarations, and a minimal case can slip past it.

It reads .scss as well as .css: the same accordion rule in a .scss file was flagged the same way.

The Enter-key finding is the one most people would not have spotted themselves. The ime-safe-enter-submit guide that ships with 1.0.1 (retrieve ime-safe-enter-submit) explains it: with an Input Method Editor for Japanese, Chinese or Korean, Enter confirms the current character candidate, so a keydown handler that submits on Enter sends the message “while they are still converting characters”. The fix is to check KeyboardEvent.isComposing before submitting. Nothing in English testing shows the bug.

What it did not catch

Bootstrap 5.3.8 has 285 .scss, .css and .js files. The scan took 482 ms, skipped 142 docs and test files, and found nothing. Scanning dist/css/bootstrap.css and js/src directly also came back with 0.

Some of that is to Bootstrap’s credit. Its form validation (scss/forms/_validation.scss) styles :invalid only under a .was-validated class that your script adds after a submit attempt, so errors already wait for the user, which is the problem the :user-invalid rule is about. But it also shows the shape of the tool again. If you built a theme on Bootstrap, the way I did in the Timber and Bootstrap post, a clean scan of the framework tells you nothing about the CSS you wrote on top of it. Point it at your own stylesheets.

The scanner itself says how much it covers: the rules come from 38 of the guides, which it puts at about 20% of the corpus. The rule list is in the bundled skills/modern-web-guidance/legacy-scan.mjs. Besides the ones above, it checks custom checkboxes and switches, scrollspy scripts, repeated :nth-child(N) rules for staggered delays, -webkit-mask and -webkit-image-set() without the standard properties, :host-context(), and a few form and autofill patterns. Floats, var, XMLHttpRequest and jQuery are not on it.

What the agent gets

For anything outside those 38 guides, the CLI’s search is how an agent finds one. search "animate accordion height to auto" returned ten guide IDs as JSON, with accordion and animate-to-intrinsic-sizes first. retrieve animate-to-intrinsic-sizes printed a 732-word guide: why max-height was a hack, numbered steps, and copyable CSS:

:root {
  /* MANDATORY: Transitions to intrinsic keywords are disabled by default for compatibility */
  interpolate-size: allow-keywords;
}

.expandable-container {
  block-size: 100px;
  overflow: hidden;
  transition: block-size 0.4s ease-out;
}

.expandable-container.is-expanded {
  block-size: auto;
}

The scan message for the same rule says to keep the max-height fallback for cross-browser support. Read that before you delete anything. The same guide’s “Fallback strategies” section (1.0.1, read 20 November 2026) gives the support status as “Limited availability”, supported by Chrome 129 and Edge 129, “Unsupported in: Firefox and Safari” (see also MDN on interpolate-size). Browsers without it jump straight to the final size. The guide is only useful if your agent keeps the fallback too.

Installing the skill is one command per agent. For Claude Code the README gives /plugin marketplace add GoogleChrome/modern-web-guidance, then /plugin install modern-web-guidance@googlechrome, and it recommends that marketplace over the copy in claude-plugins-official, which it says is no longer updated. The README also has commands for Codex, Copilot CLI, Antigravity and others. This part was not run here.

Run it on your own CSS

Run the scan on the directory that holds the CSS and JavaScript you wrote, not on the vendored framework or the build output:

DISABLE_TELEMETRY=1 npx modern-web-guidance@latest legacy-scan src/

Fix the findings that pass their “Keep when” check by hand, or pass the --json output to your agent with the matching retrieve guide. If it comes back with 0, that only means none of its 52 rules matched. Use search for the rest.

Comments

← All posts