Let the page measure whether the screen is right, not your eyes — decide by numbers, against the boundary each element must respect

Your coding agent reports that the layout is fixed. It took Playwright screenshots, and its scrollWidth > clientWidth check says horizontal overflow is zero. Then a person opens the page and the discount breakdown in a shopping-cart card is spilling into the empty margin to the right of the card. Or hovering a product card makes the cursor flicker between pointer and arrow, and the agent says it "can't reproduce it." Both happen because the visual regression check was done by eye, or by a test that measures the whole document.

How should you decide whether a screen is right?

Decide whether a screen is laid out correctly with numbers measured inside the page, not with eyes — and compare each number against the boundary that element is supposed to respect: the card it belongs in, its real size, the element that should be under the pointer. An agent looking at a screenshot can't tell a few pixels apart, and a human reviewer tends to look only inside the card. The browser already knows where every element is. You just have to ask it.

Why does a scrollWidth check miss overflow?

scrollWidth > clientWidth asks whether the document (or that box) scrolls horizontally. On a desktop layout where a narrow card sits in the middle with empty space on both sides, text that leaks out of the card lands in that empty space. The document width doesn't change, so the check returns zero. "Zero overflow" doesn't mean "nothing is out of place" — it only means "the page didn't grow a scrollbar."

What should each element be compared against?

Get each element's box with getBoundingClientRect() (MDN) and compare it not with the document but with the boundary it belongs to:

• Elements outside the main content container
• Elements outside their nearest card (or panel)
• Clipped text — the text element's own scrollWidth > clientWidth (MDN)
• Overlapping sibling text boxes
• Collapsed blocks (accordions, "show more") — run again with everything expanded; hidden rows never enter the check while collapsed

An instruction you can hand your agent:

After changing layout, do not stop at judging a screenshot.
Compare getBoundingClientRect() of every visible element against
(1) the main content container and (2) its nearest card, and print a list of
elements that fall outside, text that is clipped, and text boxes that overlap.
Expand all collapsed blocks before measuring.
Run at both desktop and mobile widths; the list must be empty to pass.

How do you measure what the pointer is actually hitting?

Hover flicker doesn't show up in a screenshot. Instead, count which element the browser picks at that spot. document.elementFromPoint(x, y) (MDN) returns the hit-test result for a coordinate. Sample a grid of dozens of points over the title and count whether every one returns the title element (or a child of it). If the results are mixed, that's where the flicker comes from.

A common case is a stack of cards tilted slightly with CSS 3D (transform-style: preserve-3d). When the text element in front and the panel behind sit at exactly the same depth, the browser picks a different one at each coordinate. backface-visibility or flattening won't fix it; lift the front element with translateZ(1px) so the depths separate. Confirm the fix with the same grid check.

What about visuals that don't seem to have numbers, like density?

Questions of "does this look right" — ink density, shadow strength, icon weight — can also be turned into numbers. Make the mockup read its own values from the canvas and print them in the caption:

1. Read the canvas pixels with getImageData and compute coverage (%), maximum alpha, and radius (px)
2. Print those values under each variant, and color the range everyone agreed is good
3. Show comparison variants at actual size (1:1). Scaled-down variants lead you to pick a different picture
4. Match the user's words ("I can't see it," "too dark") against those numbers to choose the next value

"I can't see it" becomes "coverage 3%, target 8–15%," and it gets fixed in one pass. One exception: don't judge things that change over time, like a moving camera shot, from still-frame mockups. Each frame has a different viewpoint, so the sequence just reads as jumps. Build those in the real screen behind a development switch and watch them in motion.

What happened to us

• Overflow outside a card (web calculator): Screenshot QA missed, several times, a deduction breakdown leaking out of a desktop result card into the empty margin. The scrollWidth check kept reporting zero. Only a check comparing element boxes with the card and container caught it — and it also exposed that CSS multi-column (columns) was creating an extra column in Chrome, which we replaced with grid.
• Hover flicker (3D card stack): Hovering a tilted card's title made the cursor and underline flicker. Two elements at the same depth were the cause; after translateZ(1px), we closed it by counting that every elementFromPoint sample on a grid over the title hit the title.
• Tuning brush density (canvas mockup): An agent that couldn't see the result guessed at density and weight and missed two or three times. Once the mockup printed coverage %, max alpha, and radius in its caption, the user's words and the numbers lined up and it landed in one try.

Checklist

• You know whether your check asks "does the document scroll?" or "is the element where it belongs?"
• Each element has a reference boundary (container, card)
• Collapsed blocks are expanded, and the check runs at two viewport widths
• Hover and click problems are counted with an elementFromPoint grid
• Visual variants carry measurement captions and are shown at 1:1
• Animated sequences are reviewed in the real screen, in motion