ComparisonNew

Modern Web Guidance vs No Guidance

Does your coding agent write better web code with Modern Web Guidance?

Alex Garrett-SmithNov 203 minAgents and context
Modern Web Guidance

Web platform guides from the Chrome, Edge, Firefox and MDN teams, as an agent skill

Docs for Modern Web Guidance
No Guidance

The 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.

From our runs

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.

Modern Web Guidancedrawn from run 2, the typical one

Readable, on top of the header

No Guidancedrawn from run 2, the typical one

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
MeasureModern Web GuidanceNo Guidance
Checks passed13 of 1413 of 14
Under a sticky headerReadable, on top of the header (3 of 3 runs)Hidden behind the header (3 of 3 runs)
Expected approachA popover placed by JavaScript in 3 of 3 runsA hidden element placed by JavaScript in 3 of 3 runs
JavaScript added72 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)nonenone
Guides it readinterest-triggered-tooltips, position-aware-tooltipsnone installed
Tokens, cost, time326,078 tokens, $0.46, 59 s139,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.

From our runs

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.

Modern Web Guidancedrawn from run 2, the typical one

Delete this project?

Opened before script.js arrived

No Guidancedrawn from run 3, the typical one

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
MeasureModern Web GuidanceNo Guidance
Checks passed16 of 1616 of 16
Tapped before its script arrivesOpens, 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 added20 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)nonenone
Guides it readdialog, light-dismiss-a-dialog, prevent-page-scroll-under-modal-dialognone installed
Tokens, cost, time149,730 tokens, $0.31, 38 s113,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.

Illustration, written by us

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.

From the guideillustration

Fits its text

The older wayillustration

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
MeasureFrom the guideThe older way
Based onThe guide's own exampleThe usual resize script
JavaScriptnone8 lines
On a narrower screenGrows to fit the textKeeps its height, and the text is cut off
Works in all four browsers since16 June 2026Always

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

CriterionModern Web GuidanceNo Guidance
ModalThe browser's own <dialog> in 3 of 3 runs, opened from the HTML in 2The browser's own <dialog> in 3 of 3 runs, opened by a script in all 3
Modal before its script loadsOpens, and Escape and Cancel close it, in 2 of 3 runsThe button does nothing in any of the 3 runs
TooltipA popover placed by JavaScript in 3 of 3 runs, which stays on top of a sticky headerA hidden element placed by JavaScript in 3 of 3 runs, which a sticky header covers
Hover cardCSS :hover with translate and no JavaScript, 3 of 3 runsCSS :hover with transform and no JavaScript, 3 of 3 runs
Checks passed, typical runModal 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 price1.80 million tokens, $3.21, 371 seconds0.90 million tokens, $1.54, 269 seconds

When to pick which

Pick Modern Web Guidance if
  • 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
Pick No Guidance if
  • 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.