Fidelity gate — building against a frozen visual reference

Drift that goes uncaught on the first screen multiplies onto every screen after it. Measured on one initiative that skipped this: four waves of rework plus a reconciliation audit, because "looks right" had been accepted as a verdict fourteen times.

The division of labour, which is the whole idea

Appearance is read by a MACHINE. Intent is described in WORDS.

Text, typography, colour, geometry and icons are extracted from the reference mechanically. Never let a model retype them into prose: every restatement is a lossy copy, and the source is more precise than any description of it — 22px/700/#0a2540 has exactly one interpretation, and "large bold dark-blue heading" has hundreds.

Words describe only what a static reference cannot contain: which content is an example and which is binding, where the data comes from, visibility conditions, the empty state, and the states that do not render (hover, focus, error).

The overriding rule

The reference is the only source of visual truth. Handoffs, tickets and prose describe BEHAVIOUR; appearance is settled by the reference alone. When prose disagrees with the reference about how something looks, the reference wins, you decide without asking, and you record the divergence.

• An element not in the reference does not exist. Relics of older code are not carried over without an owner's decision.
• An element in the reference must be built — if necessary as an honest-empty version in the reference's own geometry.

Step 0 — the reference lives in the repo, verified

Pull it into the repo and check it is whole before trusting it: size, the file actually ends where it should, and it renders. Work only from the in-repo copy. An incomplete reference is a STOP and a report, not something to work around — half a contract silently becomes "use your judgement".

Step 1 — the inventory, before the first line of code

Extract a machine-readable checklist from the reference. One row per element:

| # | Element | Literal text (with capitalisation) | Typography | Colours | Geometry | Icon | States and conditions |

Hard requirements, each of which has been violated at real cost:

• Literal text, including format, capitalisation and separators. A 1px rule between two phrases is an element and gets a row.
• Icons are carried over VERBATIM — the reference's own markup or asset. Substituting an icon library because a glyph "looks the same" is forbidden. A similar icon is not that icon.
• Every surface with a specific colour, and every line with its extent — where it starts and where it stops.
• Conditional elements carry the condition in the row.

If the repo has a comparator, it GENERATES the inventory and you only add the states column. Write it by hand only where no tool exists yet.

The conductor spot-checks five rows against the rendered reference before the work starts. A wrong inventory produces a confidently wrong screen.

Step 2 — the diff, when the view already exists

Before writing code, every inventory row gets MATCHES / DRIFT / MISSING, and every element present in the code but absent from the reference goes on a RELICS list with a disposition: remove (the default) or an owner gate when it is load-bearing.

"Apply the differences" without a list of the differences is forbidden. That list is the plan for the work.

Step 3 — implement the inventory, and only the inventory

If the reference uses a token, the code uses that token. If the reference defines a token and never uses it, the code does not use it either. A deviation from the reference is only ever a recorded owner decision, never an implementer's taste.

Step 4 — the gate is a MEASUREMENT, not an opinion

1. A fixture carrying the reference's own data. Same entity, same period, same numbers. Then every difference in a screenshot is a difference of appearance, not of content — which is the entire reason this step exists.
2. Side-by-side captures at the reference's own widths.
3. Computed styles dumped to JSON for the inventory's selectors and compared against the inventory's values. A disagreement about whether something is 9px or 10.5px is settled by the dump, never by looking. browser-check carries how — the capture, the dump, the deterministic waits, and the rule that a zero-size box is a failure rather than a pass. This gate owns the inventory and the verdict; it does not own the browser.
4. The verdict is the filled-in checklist, row by row, attached to the report. A narrative verdict — "looks consistent", "differences are data-only" — is REJECTED without it. This is the single rule that decides whether the gate stays a gate.
5. Failures are fixed in the same piece of work. It does not merge with failures unless the owner says so.

Three things that turn this gate back into an opinion, all observed:

• A deliberate skip is not a match. Every deviation carries a reason and lands in an explicit debt section of the report.
• Raising a tolerance until the run goes green is forbidden. That is changing the measurement to fit the answer.
• A structural selector without a text assertion silently measures the wrong element when the markup is renumbered. Anchor by an explicit attribute where you can, and always assert the text — a renumbering must produce a loud MISSING, never a quiet wrong reading.

Warm the routes up before a batch run. A cold compile produces failures that have nothing to do with fidelity, and chasing them costs a round.

Step 5 — when the data cannot fill the design

• The element stays, honest-empty, in the reference's geometry and style. Hiding a whole section because data is missing needs an owner decision — a hidden section is indistinguishable from drift.
• Missing data is a backend item raised in the report. "Pretty" versus raw values is also a data question; the front end must not hardcode a mask over it without a decision.

Step 6 — owner acceptance

At the phase gate the owner sees paired captures of full views. The checklist catches what is measurable; the owner catches the rest. Neither replaces the other, and offering only one of them is how a gate becomes a formality.