Modern Web Guidance vs No Guidance
Does your coding agent write better web code with Modern Web Guidance?
Web platform guides from the Chrome, Edge, Firefox and MDN teams, as an agent skill
Docs for Modern Web GuidanceThe same agent and starter page, with no skill or rules file installed
Without it, Claude Code already used the browser's own pop-up and a CSS hover, and the guided runs used twice the tokens. Its gains showed on a real page, in a pop-up that opens before its script loads and a tooltip a sticky header can't cover. Watch it for this year's features, once its support data is fixed, since an out-of-date note talked the agent out of CSS anchor positioning.
Put them on a real page
On a plain test page, the two sides look the same. Real pages have sticky headers, slow connections and narrow screens. Each example below adds one, so you can see which side copes. The first two are drawn from the agent's own pages in our runs, with the results those pages got in Playwright's Chromium and WebKit. The third is an illustration we wrote from the guides, and it runs in your browser.
A tooltip under a sticky header
Most apps keep their header stuck to the top of the screen. Here both pages do, the ? next to Project name sits just under it, and its tooltip is open. Turn the sticky header off to see the plain test page again.
Readable, on top of the header
Open, but hidden behind the header
The guided tooltip sits on top of the header. The unguided one is hidden behind it, in all 3 of its runs. Its z-index has to outrank the header's, and loses. The guided one is a popover, which the browser draws above everything on the page.
Popovers have worked in current Chrome, Edge, Firefox and Safari since 27 January 2025. The guided side used one in all 3 of its runs. Neither side placed it with CSS anchor positioning.
Scores and code
| Measure | Modern Web Guidance | No Guidance |
|---|---|---|
| Checks passed | 13 of 14 | 13 of 14 |
| Under a sticky header | Readable, on top of the header (3 of 3 runs) | Hidden behind the header (3 of 3 runs) |
| Expected approach | A popover placed by JavaScript in 3 of 3 runs | A hidden element placed by JavaScript in 3 of 3 runs |
| JavaScript added | 72 lines, 783 B gzipped (65 to 89 across 3 runs) | 71 lines, 601 B gzipped (65 to 74 across 3 runs) |
| Accessibility issues (axe-core) | none | none |
| Guides it read | interest-triggered-tooltips, position-aware-tooltips | none installed |
| Tokens, cost, time | 326,078 tokens, $0.46, 59 s | 139,606 tokens, $0.21, 43 s |
Modern Web Guidance
index.html
<button type="button" class="help" aria-label="Help with project name" aria-describedby="project-name-tip" data-tooltip="project-name-tip">?</button>
<div id="project-name-tip" class="tooltip" role="tooltip" popover="manual">Use a short name your team will recognise.</div>styles.css
.help:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
}
/* Positioned by script.js (top/left in viewport px); overrides the UA popover centering. */
.tooltip {
position: fixed;
inset: auto;
margin: 0;
max-width: min(16rem, calc(100vw - 16px));
padding: 0.375rem 0.625rem;
font-size: 0.875rem;
font-weight: 400;
line-height: 1.4;
color: #ffffff;
background: var(--text);
border: 0;
border-radius: 6px;
box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
}script.js
// Tooltips: a trigger with data-tooltip="<id>" shows the popover="manual"
// element with that id while it is hovered or focused. Escape dismisses it.
// It sits above the trigger, or below when there isn't room above.
document.querySelectorAll("[data-tooltip]").forEach((trigger) => {
const tip = document.getElementById(trigger.dataset.tooltip);
if (!tip) return;
const GAP = 6; // space between trigger and tooltip
const EDGE = 8; // minimum distance from the viewport edges
let hovered = false;
let focused = false;
let hideTimer;
const isOpen = () => tip.matches(":popover-open");
function position() {
// Measure at the top-left first so the available width doesn't squash it.
tip.style.top = "0px";
tip.style.left = "0px";
const anchor = trigger.getBoundingClientRect();
const { width, height } = tip.getBoundingClientRect();
const viewportWidth = document.documentElement.clientWidth;
let top = anchor.top - GAP - height;
if (top < EDGE) top = anchor.bottom + GAP; // no room above: flip below
let left = anchor.left + anchor.width / 2 - width / 2;
left = Math.max(EDGE, Math.min(left, viewportWidth - width - EDGE));
tip.style.top = `${top}px`;
tip.style.left = `${left}px`;
}
function show() {
clearTimeout(hideTimer);
if (!isOpen()) tip.showPopover();
position();
}
function hide() {
clearTimeout(hideTimer);
if (isOpen()) tip.hidePopover();
}
// Short delay so the pointer can cross the gap onto the tooltip itself.
function hideSoon() {
clearTimeout(hideTimer);
hideTimer = setTimeout(() => {
if (!hovered && !focused) hide();
}, 100);
}
function onPointerEnter(event) {
if (event.pointerType === "touch") return;
hovered = true;
show();
}
function onPointerLeave(event) {
if (event.pointerType === "touch") return;
hovered = false;
hideSoon();
}
trigger.addEventListener("pointerenter", onPointerEnter);
trigger.addEventListener("pointerleave", onPointerLeave);
// Keep it open while the pointer is over the tooltip, so it can be read.
tip.addEventListener("pointerenter", onPointerEnter);
tip.addEventListener("pointerleave", onPointerLeave);
trigger.addEventListener("focus", () => {
focused = true;
show();
});
trigger.addEventListener("blur", () => {
focused = false;
hideSoon();
});
// Tap/click shows it too (Safari doesn't focus buttons on click).
trigger.addEventListener("click", show);
document.addEventListener("keydown", (event) => {
if (event.key === "Escape" && isOpen()) hide();
});
// Tap elsewhere closes it on touch devices.
document.addEventListener("pointerdown", (event) => {
if (isOpen() && !trigger.contains(event.target) && !tip.contains(event.target)) {
hovered = false;
hide();
}
});
// The tooltip is fixed to the viewport, so follow the trigger.
window.addEventListener("scroll", () => isOpen() && position(), { passive: true, capture: true });
window.addEventListener("resize", () => isOpen() && position());
});No Guidance
index.html
<span class="tooltip-wrap">
<button type="button" class="help" aria-label="Help with project name" aria-describedby="project-name-tip">?</button>
<span class="tooltip" id="project-name-tip" role="tooltip" hidden>Use a short name your team will recognise.</span>
</span>styles.css
.help:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
}
.tooltip-wrap {
position: relative;
display: inline-flex;
}
.tooltip {
--gap: 0.5rem;
--shift: 0px;
position: absolute;
left: 50%;
bottom: calc(100% + var(--gap));
z-index: 10;
width: max-content;
max-width: min(16rem, calc(100vw - 1rem));
padding: 0.375rem 0.625rem;
font-size: 0.875rem;
font-weight: 400;
line-height: 1.4;
color: #ffffff;
background: var(--text);
border-radius: 6px;
transform: translateX(calc(-50% + var(--shift)));
}
.tooltip[hidden] {
display: none;
}
/* Small arrow pointing at the button. */
.tooltip::after {
content: "";
position: absolute;
left: calc(50% - var(--shift));
top: 100%;
border: 5px solid transparent;
border-top-color: var(--text);
transform: translateX(-50%);
}
.tooltip.is-below {
bottom: auto;
top: calc(100% + var(--gap));
}
.tooltip.is-below::after {
top: auto;
bottom: 100%;
border-top-color: transparent;
border-bottom-color: var(--text);
}
@media (forced-colors: active) {
.tooltip {
border: 1px solid CanvasText;
}
}script.js
// Tooltips: shown on hover or keyboard focus, hidden on leave, blur or Escape.
// Placed above the trigger, or below it when there isn't room above.
document.querySelectorAll(".tooltip-wrap").forEach(function (wrap) {
var trigger = wrap.querySelector(".help");
var tip = wrap.querySelector(".tooltip");
var EDGE = 8; // Minimum distance from the viewport edge, in px.
var hovered = false;
var focused = false;
function position() {
// Reset, then measure in the default (above, centred) position.
tip.classList.remove("is-below");
tip.style.setProperty("--shift", "0px");
var rect = tip.getBoundingClientRect();
if (rect.top < EDGE) {
tip.classList.add("is-below");
}
// Nudge sideways if it would run off the left or right edge.
var shift = 0;
var viewportWidth = document.documentElement.clientWidth;
if (rect.left < EDGE) {
shift = EDGE - rect.left;
} else if (rect.right > viewportWidth - EDGE) {
shift = viewportWidth - EDGE - rect.right;
}
tip.style.setProperty("--shift", shift + "px");
}
function show() {
tip.hidden = false;
position();
}
function hide() {
tip.hidden = true;
}
function update() {
if (hovered || focused) {
show();
} else {
hide();
}
}
// Hovering the tooltip itself keeps it open, so it can be read or selected.
wrap.addEventListener("mouseenter", function () {
hovered = true;
update();
});
wrap.addEventListener("mouseleave", function () {
hovered = false;
update();
});
trigger.addEventListener("focus", function () {
focused = true;
update();
});
trigger.addEventListener("blur", function () {
focused = false;
update();
});
// Tapping on touch screens (and clicking in Safari, which doesn't focus
// buttons on click) should also reveal it.
trigger.addEventListener("click", show);
document.addEventListener("pointerdown", function (event) {
if (!wrap.contains(event.target) && !focused) {
hovered = false;
hide();
}
});
// Escape dismisses it wherever focus is, e.g. while just hovering.
document.addEventListener("keydown", function (event) {
if (event.key === "Escape" && !tip.hidden) {
hide();
}
});
// Keep it in the right place if the page moves while it's open.
window.addEventListener("scroll", function () {
if (!tip.hidden) position();
}, { passive: true });
window.addEventListener("resize", function () {
if (!tip.hidden) position();
});
});Checks run in Playwright's Chromium and WebKit, Firefox from MDN's compat data, and again with the sticky header for every run. Tokens, cost and time are for the typical run, at list price. The pages above are drawn from that run.
A delete pop-up on a slow connection
Both sides used the browser's own pop-up, <dialog>. Here each page's script takes 4 seconds to arrive, as it can on a phone, and Delete project is tapped before it does. Press it yourself, during a replay or after one.
Delete this project?
Opened before script.js arrived
Tapped, but nothing happened
The guided pop-up opens straight away, because its button opens it from the HTML with command="show-modal". The unguided button needs its script, so the tap is lost.
Opening a pop-up from the HTML (invoker commands) has worked in current Chrome, Edge, Firefox and Safari since 12 December 2025. The guided side did it in 2 of its 3 runs.
Scores and code
| Measure | Modern Web Guidance | No Guidance |
|---|---|---|
| Checks passed | 16 of 16 | 16 of 16 |
| Tapped before its script arrives | Opens, and Escape and Cancel close it (2 of 3 runs) | Nothing happens (0 of 3 runs open) |
| Expected approach | <dialog> in 3 of 3 runs, opened from the HTML in 2 | <dialog> in 3 of 3 runs, opened by a script in all 3 |
| JavaScript added | 20 lines, 321 B gzipped (20 to 26 across 3 runs) | 20 lines, 285 B gzipped (20 to 22 across 3 runs) |
| Accessibility issues (axe-core) | none | none |
| Guides it read | dialog, light-dismiss-a-dialog, prevent-page-scroll-under-modal-dialog | none installed |
| Tokens, cost, time | 149,730 tokens, $0.31, 38 s | 113,984 tokens, $0.20, 37 s |
Modern Web Guidance
index.html
<button type="button" class="button button-danger" id="delete-project" command="show-modal" commandfor="delete-dialog">Delete project</button>
<dialog id="delete-dialog" class="confirm-dialog" closedby="any" aria-labelledby="delete-dialog-title">
<h2 id="delete-dialog-title">Delete this project?</h2>
<form method="dialog" class="dialog-actions">
<button value="cancel" class="button button-secondary" autofocus>Cancel</button>
<button value="delete" class="button button-danger">Delete</button>
</form>
</dialog>styles.css
.button-secondary {
color: var(--text);
background: var(--bg);
border: 1px solid var(--border);
}
.confirm-dialog {
width: min(24rem, calc(100% - 2rem));
padding: 1.5rem;
color: var(--text);
background: var(--surface);
border: 1px solid var(--border);
border-radius: var(--radius);
box-shadow: 0 12px 32px rgb(0 0 0 / 0.2);
}
.confirm-dialog h2 {
margin: 0 0 1.25rem;
}
.dialog-actions {
display: flex;
justify-content: flex-end;
gap: 0.75rem;
}
/* Stop scroll gestures inside the dialog or over the backdrop reaching the page. */
dialog:modal {
overscroll-behavior: contain;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.45);
overflow: hidden;
overscroll-behavior: contain;
}
/* Safari doesn't yet honour overscroll-behavior on non-scrolling containers,
so also lock the root while a modal is open. scrollbar-gutter keeps the
scrollbar's space reserved so the page doesn't shift sideways. */
:root:has(dialog:modal) {
overflow: hidden;
scrollbar-gutter: stable;
}script.js
// Click-outside-to-close for browsers without <dialog closedby> (currently Safari).
// Esc already closes modal dialogs everywhere.
if (!('closedBy' in HTMLDialogElement.prototype)) {
// Test the pointer position rather than event.target: the <dialog> itself is also
// the target for clicks on its own padding.
const isOutside = (event, dialog) => {
const rect = dialog.getBoundingClientRect();
return (
event.clientX < rect.left ||
event.clientX > rect.right ||
event.clientY < rect.top ||
event.clientY > rect.bottom
);
};
for (const dialog of document.querySelectorAll('dialog[closedby="any"]')) {
let pressedOutside = false;
dialog.addEventListener('pointerdown', (event) => {
pressedOutside = isOutside(event, dialog);
});
// Require both press and release outside, so a text-selection drag that
// ends on the backdrop doesn't close the dialog.
dialog.addEventListener('pointerup', (event) => {
if (pressedOutside && isOutside(event, dialog)) dialog.close();
});
}
}No Guidance
index.html
<dialog class="modal" id="delete-dialog" aria-labelledby="delete-dialog-heading">
<form method="dialog" class="modal-body">
<h2 id="delete-dialog-heading">Delete this project?</h2>
<div class="modal-actions">
<button type="submit" class="button button-secondary" value="cancel" autofocus>Cancel</button>
<button type="submit" class="button button-danger" value="delete">Delete</button>
</div>
</form>
</dialog>styles.css
.button-secondary {
color: var(--text);
background: var(--surface);
box-shadow: inset 0 0 0 1px var(--border);
}
/* Stop the page behind an open modal from scrolling. */
html:has(dialog[open]:modal) {
overflow: hidden;
}
.modal {
width: min(24rem, calc(100% - 2rem));
padding: 0; /* The inner body fills the dialog, so clicks on the dialog itself are backdrop clicks. */
color: var(--text);
background: var(--surface);
border: 0;
border-radius: var(--radius);
box-shadow: 0 10px 30px rgb(0 0 0 / 0.2);
}
.modal::backdrop {
background: rgb(28 34 48 / 0.5);
}
.modal-body {
padding: 1.5rem;
}
.modal-body h2 {
margin: 0 0 1.5rem;
}
.modal-actions {
display: flex;
justify-content: flex-end;
gap: 0.75rem;
}script.js
const deleteButton = document.getElementById('delete-project');
const deleteDialog = document.getElementById('delete-dialog');
deleteButton.addEventListener('click', () => {
// returnValue persists between openings; clear it so closing with Escape
// after an earlier Delete isn't mistaken for another Delete.
deleteDialog.returnValue = '';
deleteDialog.showModal();
});
// Close when clicking the backdrop. The dialog has no padding and its inner
// form fills it, so a click whose target is the dialog itself landed outside
// the visible box. Checking where the press started too means dragging from
// inside the box (e.g. selecting text) and releasing outside won't close it.
let pressStartedOnBackdrop = false;
deleteDialog.addEventListener('pointerdown', (event) => {
pressStartedOnBackdrop = event.target === deleteDialog;
});
deleteDialog.addEventListener('click', (event) => {
if (event.target === deleteDialog && pressStartedOnBackdrop) {
deleteDialog.close('cancel');
}
pressStartedOnBackdrop = false;
});
// Escape closes the dialog natively; the Cancel and Delete buttons close it via
// the form's method="dialog". deleteDialog.returnValue is "delete" when the
// Delete button was pressed, ready for when deletion is implemented.
deleteDialog.addEventListener('close', () => {
if (deleteDialog.returnValue === 'delete') {
// TODO: delete the project.
}
});Checks run in Playwright's Chromium and WebKit, Firefox from MDN's compat data, and again with the slow script for every run. Tokens, cost and time are for the typical run, at list price. The pages above are drawn from that run.
A description box on a narrower screen
The guide's box fits its text with one line of CSS, field-sizing: content. The older one sets its height from a script as you type. Both fit at full width. Then the screen gets narrower, like a phone turned upright or a sidebar opening.
Fits its text
Fits its text
At full width, both boxes fit their text.
field-sizing has worked in current Chrome, Edge, Firefox and Safari since 16 June 2026, when Firefox 152 added it.
The code
| Measure | From the guide | The older way |
|---|---|---|
| Based on | The guide's own example | The usual resize script |
| JavaScript | none | 8 lines |
| On a narrower screen | Grows to fit the text | Keeps its height, and the text is cut off |
| Works in all four browsers since | 16 June 2026 | Always |
From the guide
styles.css
/* The Description box fits its text, from the guide's example. No JavaScript. */
#project-description {
field-sizing: content;
min-block-size: 3lh;
max-block-size: 10lh;
}The older way
styles.css
/* The Description box is resized by the script in script.js. */
#project-description {
max-height: 10lh;
}script.js
// Grow the Description box to fit its text, on load and on every keystroke.
const description = document.querySelector('#project-description');
function fitToText() {
description.style.height = 'auto';
// scrollHeight leaves out the border, so add it back or a scrollbar appears.
const border = description.offsetHeight - description.clientHeight;
description.style.height = description.scrollHeight + border + 'px';
}
description.addEventListener('input', fitToText);
fitToText();Written by us on 15 November 2026 from the installed guides, not by the agent. Checked in Playwright's Chromium and WebKit, at full width and narrowed. The two boxes above run this CSS and script in your browser.
The hover card isn't here, because both sides wrote the same CSS :hover rule. It's in the table below.
The project's own evals report a bigger lift. In their 8 November snapshot, Claude Code on Opus 5.5 scored 57% without it and 88% with it, across 215 tasks of their own. Ours is a demo, not a benchmark.
Side by side
| Criterion | Modern Web Guidance | No Guidance |
|---|---|---|
| Modal | The browser's own <dialog> in 3 of 3 runs, opened from the HTML in 2 | The browser's own <dialog> in 3 of 3 runs, opened by a script in all 3 |
| Modal before its script loads | Opens, and Escape and Cancel close it, in 2 of 3 runs | The button does nothing in any of the 3 runs |
| Tooltip | A popover placed by JavaScript in 3 of 3 runs, which stays on top of a sticky header | A hidden element placed by JavaScript in 3 of 3 runs, which a sticky header covers |
| Hover card | CSS :hover with translate and no JavaScript, 3 of 3 runs | CSS :hover with transform and no JavaScript, 3 of 3 runs |
| Checks passed, typical run | Modal 16 of 16, tooltip 13 of 14 (no anchor positioning), hover card 8 of 8, no accessibility issues (axe-core) | Modal 16 of 16, tooltip 13 of 14 (no anchor positioning), hover card 8 of 8, no accessibility issues (axe-core) |
| Each side's 9 runs, at list price | 1.80 million tokens, $3.21, 371 seconds | 0.90 million tokens, $1.54, 269 seconds |
When to pick which
- You build with features that only reached every browser this year, like text boxes that size themselves with CSS
- Your agent still hands you older patterns, like a pop-up built from a div
- Your pages should still work when their JavaScript is slow or fails to load
- Your agent already reaches for the browser's own pieces
- The work is everyday UI and tokens or time matter
How we tested
- Task
- Claude Code got the same three jobs on a plain starter page, three runs a side, with and without Modern Web Guidance. They were a delete confirmation pop-up, a tooltip that flips below near the top of the screen, and a lift on hover for project cards. Each page was checked in Chromium and WebKit, with JavaScript off, a sticky header and a slow script, and for Firefox against MDN's compat data.
- Evidence
- 18 recorded runs on 14 November 2026, scored with Playwright and axe-core. The text box is an illustration we wrote from the guide.
- With
- Claude Code 2.1.325, headless, Claude Opus 5.5, pinned for every run, Modern Web Guidance 1.0.0, project skill, default settings, Playwright 1.65.1 with Chromium 159 and WebKit 27.2, axe-core 4.14.0, MDN browser-compat-data 8.1.9, for Firefox 160
Updates
Published.