Layout thresholds — the numbers, and why they are those numbers

Every value here is defined once in THRESHOLDS at the top of scripts/decidueye.mjs and emitted verbatim in each run’s decidueye.json. This file is the reasoning; the code is the value. If the two disagree, the code is wrong, not this page — but they are meant to move together.

One bias runs through all of it: a false positive here is worse than a miss. A composition finding cannot be proved from a number the way an overflow can, so a reviewer decides whether it matters — and a check that fires on every centred site trains people to close the report. Every threshold is set where a human looking at the section would agree something is off, not where the measurement first becomes non-zero.

Where the checks run

Two categories are excluded outright:

• Site chrome (header, footer, nav, and anything inside them). A masthead and a footer are sparse by design. Grading their emptiness reports every site on the internet.
• A section that paints its own backdrop (background-image on the section). A full-bleed hero is not empty ground; it is the picture. Nothing under a backdrop is graded for blankness.

(a) Blank area

The single most important decision in this file: blank space is measured inside the page’s content column, never inside the full-bleed section box.

A section on a centred site is a 1920px box wrapping an 1184px measure: ~40% gutter, by design, on every section of every such page. Grading the box reports the whole page and means nothing. So the column is derived from the page itself — the median left and right ink edge across its graded sections. Median, not min or max, so one full-bleed band or one narrow rail cannot redefine the column for everything else. Under three usable sections there is no median worth having and these checks do not run at all.

What counts as ink: line boxes of real text (via a Range, so glyph extent, not the element’s padding box), replaced media (img, svg, video, canvas, iframe, picture), form controls, any painted background-image, a background-color differing from the section’s own, and any real border. Each rectangle is first clipped to every hidden-overflow ancestor’s clip rect — a collapsed accordion’s box runs far past what is painted of it, and counting it fills a hole that is really there.

Generated content is ink. A ::before / ::after with text or a painted background counts — its box is estimated from the computed offsets and size when they are set, otherwise from the run of its text at its font size. A chapter numeral or a stage number drawn that way keeps its rail from reading as empty.

(b) Image fit

Excluded from the thumbnail floor: anything with alt="" or role="presentation", anything whose class or filename says icon / logo / avatar / badge / sprite / arrow / chevron / mark / seal / emblem / crest / credential / accredit / award / partner, anything whose alt text reads as a logo or a credential (“logo”, “certified”, “accredited”, “member of”, “board-certified”, “fellow of”, “society”, “association”, “award”), any image in a strip — three or more images under one box all rendered under the floor, which is a trust-mark row or a press-logo row whatever the files are called — and anything inside a nav, header, footer or button. Those are all legitimately tiny.

CSS background images with background-size: cover are graded on the same aspect rule as <img>. The hero-crop defect lives on a background as often as on an element, and the source’s natural size only exists once the file is decoded — so the measurement decodes it, with a 4-second cap per image.

(c) Sibling consistency

Width variance is graded only where equal columns were declared — a display: grid container. A flex row of chips, tags or footer links is meant to hug its own text, and grading that reports every tag cloud on the web. Height variance is graded in both, because a short card in a row of tall ones is wrong either way. A row also has to be a real repeated tile set: every child the same element type, each at least 60×24px.

(d) Wrap

(e) Column balance

A “two-column row” is a flex or grid container with exactly two visible children whose tops are within 40px of each other, each at least 100px wide, together spanning at least 70% of the container. Anything looser starts pairing a heading with the body under it.

(f) Overlap

The candidate set is deliberately narrow, because this is the skill’s other FAIL:

• Only text runs and images. Decorative absolutely-positioned ground under content is the normal case on every modern site; text on text, or text on a picture, is the defect.
• One candidate per line box, not per element. An element’s bounding box is the union of its line fragments, so a wrapped inline spans the full measure and “contains” every sibling on its first line, and a block’s box carries its leading, so two consecutive paragraphs read as a 16px collision. Both were live false positives before line boxes replaced element boxes.
• Nothing inside a fixed or sticky ancestor (a sticky header legitimately overlays content), nothing inside a hidden drawer, modal, lightbox, popup or off-canvas shell, and nothing clipped to nothing by an ancestor’s overflow.

(g) Alignment

Centred and right-aligned headings are excluded — their left edge varies with their own text length by definition — as are headings out of normal flow. The companion heading-offset check compares each heading against the first left-aligned paragraph or list item beneath it in its own section: the case where a heading and its own text column disagree, which no page-wide edge count can see.

The vision pass

--verify crops each measured section out of the desktop capture and puts one fixed rubric to a vision model: subject cropped, unintended empty space, misaligned, text/image mismatch, or ok. It has no threshold, because it is not a measurement.

It is advisory by construction: its answers are only ever REVIEW, never FAIL, and a run without GEMINI_API_KEY is SKIPPED for that step with the key named while every measured check runs unchanged. A model’s opinion about a picture is a second reader, not a gate. Capped at 14 crops per page and at twice the viewport height per crop.