Checks you can trust
Checking what the browser actually drew
A test that records where the browser actually put each piece of a page, and checks those boxes against written layout rules.
One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.
An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.
The problem
The checks most codebases already run each read something other than the page on screen. A linter reads the source for known mistakes. A type checker reads the types. An accessibility check reads the structure a screen reader is given. A screenshot test tells you the pixels changed, but not whether the change was wrong.
Some layout bugs live in the gap between those. A tab bar whose underline stops short of the last tab. Group labels that sit on a different left edge from the rows below them. A button 30 pixels tall in a row of 28-pixel buttons. I met this after a sweep had moved every margin in a codebase on to a short list of agreed sizes. Two screens still looked wrong, and I had no check that could say why.
The idea
Give the page a vocabulary and check it against the geometry. Each component, a reusable piece of interface, carries one attribute saying what it is. A test renders each component in a real browser and records every named element as a box: its name and its rectangle. A separate function, with no access to the page, takes the boxes and judges them against written rules, such as "a control is one of the agreed heights".
Elements that lay themselves out but carry no name are counted, because no rule can reach them. Both counts, rule breaches and unnamed boxes, are held per file and may only go down, the way a ratchet holds a count (another pattern here).
A version small enough to read
This is the judging half on its own. In a real setup a browser test records the boxes. Here they are written out by hand, which works because the judge never needs the page. The screen below breaks each of the four rules once, on purpose.
// Judges rendered boxes against written layout rules. In a real setup a// browser test records the boxes; here they are written out by hand, because// the judge never needs the page. Run: bun judge.tstype Box = { part?: string; x: number; y: number; w: number; h: number; laysOut?: boolean };
const CONTROL_HEIGHTS = [28, 36]; // the agreed sizesconst GAPS = [4, 8, 16];
const contracts: Record<string, (boxes: Box[]) => string[]> = { "a control is one of the agreed heights": (boxes) => boxes.filter((b) => b.part === "control" && !CONTROL_HEIGHTS.includes(b.h)) .map((b) => `control at x=${b.x} is ${b.h}px tall; allowed: ${CONTROL_HEIGHTS.join(", ")}`), "a tab bar's underline reaches its last tab": (boxes) => { const tabs = boxes.filter((b) => b.part === "tab"); const rule = boxes.find((b) => b.part === "tabs.rule"); const end = Math.max(...tabs.map((t) => t.x + t.w)); return rule && rule.x + rule.w < end ? [`underline stops at ${rule.x + rule.w}px, last tab ends at ${end}px`] : []; }, "rows are an agreed gap apart": (boxes) => { const rows = boxes.filter((b) => b.part === "row").sort((a, b) => a.y - b.y); return rows.slice(1).flatMap((r, i) => { const gap = r.y - (rows[i].y + rows[i].h); return GAPS.includes(gap) ? [] : [`gap of ${gap}px above the row at y=${r.y}; allowed: ${GAPS.join(", ")}`]; }); }, "every box that does its own layout says what it is": (boxes) => boxes.filter((b) => b.laysOut && !b.part).map((b) => `unclassified box at x=${b.x}, y=${b.y}`),};
const screen: Box[] = [ { part: "tab", x: 0, y: 0, w: 80, h: 36 }, { part: "tab", x: 80, y: 0, w: 80, h: 36 }, { part: "tab", x: 160, y: 0, w: 96, h: 36 }, { part: "tabs.rule", x: 0, y: 36, w: 240, h: 1 }, { part: "row", x: 0, y: 48, w: 256, h: 40 }, { part: "row", x: 0, y: 96, w: 256, h: 40 }, { part: "row", x: 0, y: 142, w: 256, h: 40 }, { part: "control", x: 0, y: 200, w: 90, h: 28 }, { part: "control", x: 98, y: 200, w: 90, h: 30 }, { x: 0, y: 240, w: 256, h: 60, laysOut: true },];
for (const [rule, judge] of Object.entries(contracts)) { const found = judge(screen); console.log(`${found.length ? "FAIL" : "ok "} ${rule}${found.map((f) => `\n ${f}`).join("")}`);}Run with Bun, a JavaScript runtime, it prints:
FAIL a control is one of the agreed heights control at x=98 is 30px tall; allowed: 28, 36FAIL a tab bar's underline reaches its last tab underline stops at 240px, last tab ends at 256pxFAIL rows are an agreed gap apart gap of 6px above the row at y=142; allowed: 4, 8, 16FAIL every box that does its own layout says what it is unclassified box at x=0, y=240Where the plain form falls short
The plain form is a screenshot test and a person looking at it. I think it misses these.
- A screenshot test reports change, not error. It flags every intended change too, so the reviewer learns to approve the difference. A rule with a number in it says what is off, and by how much.
- A rule can only reach what is named. Counting the unnamed boxes that lay themselves out shows how much of the page is outside every rule.
- A rule with no agreed size cannot be judged. "Even spacing" is a matter of taste. "Gaps are 4, 8 or 16 pixels" is something a test can hold.
- Only what a rule describes is caught. So new rules come from people looking. Capture the screens with the boxes drawn, number what looks wrong, and rule on each finding. An accepted one becomes a fix or a new rule. A rejected one is written down, so it is not raised again.
- A judge tied to the browser is slow to test. Keeping the judge a plain function of boxes in, breaches out, means most of it is tested in milliseconds without a browser.
In the one codebase where I've run the full version, 1,459 rule breaches and 16,095 unnamed boxes both went to zero over five days, in about 40 pull requests, the reviewed changes merged into the code. The review by eye described above raised 248 findings, and 222 of them were accepted.
Trade-offs
- Every component needs a name. That is work up front, and the names are kept in one file, a registry, which is one more file to keep right.
- Real browsers are slow. Rendering every component in a browser adds minutes to the automated checks on each change.
- Rules can be too strict. A deliberate exception, such as one larger control on a landing page, needs a way to say so. Otherwise people start fighting the check.
When to use it, and when not to
It suits a component library or an app with many screens built from shared parts, where the same few layout mistakes keep coming back. It is too much for a handful of pages, and it does not fit work where the layout is meant to be loose, such as a one-off illustration.
A fuller example
The fuller version, built for a component library, is linked at the foot of this page. It has fourteen kinds of rule, the browser test that records the boxes, and the per-file counts. It is early, and its changelog says which parts have been published so far.
Example. The layout check, on GitHub
A draft skill for this pattern
A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/layout-contracts/. It is a draft, and I haven't tried it on anyone else's project yet.
---name: layout-contractsdescription: Use when a component library or app has layout bugs that lint, type checks and screenshot tests miss (an underline that stops short, a control a few pixels taller than its neighbours, uneven gaps). Names each component, records its rendered box in a real browser, and judges the boxes against written rules.---
# Layout contracts
Lint reads source, type checks read types, screenshot tests say the pixelschanged. None of them reads where the browser put each box, which is wheresome layout bugs live. Give the page a vocabulary and check the boxes.
## Before you start
You need a way to render each component in a real browser in a test, such asStorybook, a tool that renders each component on its own, with its test runner. Agree a short list of sizes first:control heights, gaps. A rule needs a number to hold to.
## Build it
1. Name the parts. Each component carries one attribute saying what it is, such as `data-part="row.title"`. Keep a registry of the names: purpose, which parts it may sit inside, which rules apply to it.2. Measure. After each component renders, walk the elements and record each named one as a box: its name and rectangle.3. Judge. Write a function that takes the boxes and the registry and returns violations. It never touches the page, so most of it is tested without a browser. Start with three or four rules you have actually seen broken.4. Count boxes that do their own layout but carry no name. They are where the rules cannot reach.5. Hold the counts with a ratchet. Record each file's violation and unnamed counts; they may only go down.6. Write each message with the numbers: "30px tall; allowed: 28, 36".
## Review
The judge catches only what a rule describes. Capture screens with the boxesdrawn, number what looks wrong, and have a person rule on each. An acceptedfinding becomes a fix or a new rule. A rejected one is written down so it isnot raised again.
## What it does not do
It does not judge anything unnamed, or anything no rule describes. It is nota replacement for looking at the screen; it makes what you saw once stayfixed.