ENPT

Modern Web Guidance

Last week, the Chrome team released Modern Web Guidance 1.0. It is a set of agent skills that gives coding agents up-to-date advice about the web platform. The Firefox, Edge, and MDN teams maintain it together with Chrome.

The problem it addresses is simple. Models learn from years of old code, so they often write the JavaScript workarounds we needed a few years ago, even when the browser can now do the job by itself. I installed it on this blog to see what it would change.

How it works

The skill tells the agent to look up a guide before it writes HTML, CSS, or client-side JavaScript. The lookup is a small CLI:

npx modern-web-guidance@latest search "light dismiss modal dialog"
npx modern-web-guidance@latest retrieve "dialog"

search returns a list of guide IDs, and retrieve prints the guide. Each guide is short and specific. It says what to use, what to avoid, and which browsers support each feature. Browser engineers review every guide, and accessibility specialists also review the guides for user-facing features.

There is also legacy-scan, which checks existing code for outdated patterns without calling a model. It only covers the guides that have rules a static checker can match, about 20% of them.

Installing it

npx modern-web-guidance@latest install

I installed it for Claude Code in the blog repository. That added the skill to .claude/skills/, so any agent session that works on the blog uses it. Then I set the browser support target:

npx modern-web-guidance@latest set-baseline newly

This writes a .mwgrc file. Baseline “Newly available” means a feature works in the latest version of every major browser. With this target, the guides don’t ask for fallback code for those features, which keeps the code small.

The CLI sends anonymous usage data to Google. Set DISABLE_TELEMETRY=1 in your shell profile to turn it off.

What the scan found

With the skill installed, the first thing I did was run legacy-scan on the blog’s code:

npx modern-web-guidance@latest legacy-scan

It found three items, all in the stylesheet. Two were ::-webkit-scrollbar rules that the standard scrollbar-width and scrollbar-color properties now replace. The third was a list of ten rules that delayed the animation of each post card on the home page:

.post-card:nth-child(1) { animation-delay: .04s; }
.post-card:nth-child(2) { animation-delay: .08s; }
/* ...eight more... */

The new sibling-index() function turns them into one rule:

.post-card { animation-delay: calc(sibling-index() * .04s); }

What the guides changed

The scan was the smaller part. The bigger changes came from asking the agent to rewrite specific components using the guides.

Search. The search box was a hand-built overlay with code for the Esc key, clicks outside, and moving focus back. It is now a native <dialog> opened with showModal(). The browser keeps focus inside the dialog, makes the page behind it inert, and returns focus when it closes. The closedby="any" attribute closes it when you click outside. Safari doesn’t support closedby yet, so a few lines of fallback code handle that case.

Table of contents. The “Contents” panel is now a popover. The popovertarget attribute on the button opens and closes it, and the browser handles clicks outside and the Esc key. CSS anchor positioning keeps the panel under its button. Firefox doesn’t support anchor positioning yet, so there the panel opens in the center of the screen.

Reading progress bar. The bar at the top of each post used a scroll listener. It is now a CSS scroll-driven animation, so the browser updates it without a scroll listener:

.progress-bar {
  animation: grow-progress auto linear both;
  animation-timeline: scroll(root block);
}

Mobile menu. This was a real accessibility bug. On small screens, the closed menu was off-screen but still reachable with the Tab key. It is now inert while closed, and the page behind it is inert while it is open.

The guides also caught details I would have missed. For example, the dialog guide says not to stop the page from scrolling with overflow: hidden on <body>, because that removes the scrollbar and shifts the layout. It uses overscroll-behavior: contain on the dialog and its backdrop instead.

Final thoughts

The site’s JavaScript is 38 lines shorter, and the search, contents panel, and menu now behave the way the browser’s built-in controls do. What I liked most is that each guide includes browser support data and a fallback plan, which is the part I usually have to look up on MDN by myself. The skill stays in the repository, so the next time an agent edits this blog, it starts from the same guidance.

Search

Press / or Ctrl+K