Notes · 02

How a reference
is born.

A reference starts as a screenshot, and a screenshot is a lossy thing. It holds the pixels and drops the rest: the exact hues, the shadow values, the easing, the interactions that only exist once you click. Turning one back into working code is not tracing. It is reading. This note is how uistash does that reading, and why the last step is a measurement instead of a promise.

01 · Reading, not tracing

A screenshot is evidence, not a template.

An image lands from wherever you found it. The first temptation is to glance at it and start typing markup that looks about right. That is how you get a rebuild that passes at a squint and falls apart under inspection: the corner radius is a guess, the shadow is invented, the type scale drifts a few percent on every line.

The work is to treat the screenshot as the record of decisions a person made, and to recover the decisions rather than the surface. Everything that follows is built to make that recovery precise, and then to prove it.

02 · The contract

Tokens come out first.

Nothing gets built until the values are pulled out and written down. Colors become tokens, each with the rule for what it is allowed to mean. Spacing becomes a scale. Type becomes families and sizes. This file, tokens.css, is extracted before a single component exists, and it functions as a contract: everything downstream has to be built from it, not around it.

The build order: tokens first as a contract, then components one file each, assembly, verifying with a camera and a ruler, and documenting into a DESIGN.md. A sample rides the rail from start to finish. 01tokensthe contract 02components× N, one file each 03assemblythe whole page 04verifyingcamera + ruler 05documentingDESIGN.md
The recipe order is fixed. Tokens are extracted first and everything downstream is measured against them.

Fixing the vocabulary first is what keeps a reproduction coherent instead of a pile of one-off values that happen to sit near each other. Get the contract right and the rest of the build has fewer ways to go wrong.

03 · Building

Everything speaks the contract's vocabulary.

With the tokens fixed, the build runs in a set order: tokens, then components one file at a time, then assembly into the whole page, then verifying, then documenting. Each component imports the tokens verbatim, carries only the styles it needs, and ships zero dependencies.

The order is not decoration. A component built after the tokens can only speak in the tokens' vocabulary, so the page holds together by construction rather than by luck. Coherence is not a pass you run at the end. It is a property of the sequence.

04 · The camera and the ruler

Then it gets checked against the original.

Here is the part most tools skip. A browser renders the rebuild, screenshots it at the reference's declared canvas, and the two images are compared region by region. Where they disagree, the difference is a number, weighted toward the parts a person actually looks at.

A grid of image regions, each filled to its own match against the original. Most regions register densely; two weak regions read sparse and are where a refinement turn is spent. A gauge marks the fixed constants: 0.82 to pass, a 0.51 ceiling when the framing is wrong. rebuild ÷ original, region by region 0.82 pass0.51 framing ceilingthis run, earned
The score is a measurement, not a claim. A wrong scale is capped below the pass line so it can never stamp as a win.

If the match falls short, the build spends a refinement turn on exactly the regions that missed, up to twice, and measures again. There is a deliberate trap in the scoring: if the rebuild is drawn at the wrong scale, a phone floating in a desktop void, the framing failure is caught and the score is capped below the pass line. A pretty specimen at the wrong size cannot buy its way to a good number.

05 · Earned

A score is a measurement, not an adjective.

The fidelity number a reference carries is something a person can re-run, not a word the model gave itself. That distinction is the whole posture. A screenshot is somebody's finished work, and the honest way to admire it is to reproduce it precisely enough that the copy could be held up against the original and hold.

Precision is the form respect takes here. The reference is born the moment the rebuild survives the comparison and the reasoning is written down beside it, in a DESIGN.md, so the next reader, human or agent, inherits the decisions instead of guessing them again.