Verifying a design against the running app

Reading the code and deciding it looks right is not verification. A fidelity check renders the real thing, reads it back, and compares it to the design node by node.

This is the finish condition for design work: a design transfer proves the design moved, not that the code followed.

How a check runs

1. The app comes up. A dev server for web, a simulator run for iOS or Android. The agent starts it rather than asking you to.
2. The result is observed. On web, the rendered nodes. On native, the accessibility tree of the running app.
3. It is compared to a reference. In order of authority: Figma metadata when the screen came from Figma, otherwise the design's own geometry.
4. Findings come back named. Each one identifies the layer and the axis, for example "StatusBadge > Dot is 8px low", so one fix per iteration is real progress.

Reading the findings

• Blocking findings must reach zero, at every width the design was authored at.
• Text-metric findings are advisory. Figma and a rendering engine never agree to the pixel on glyph advance, and blocking on that hides real layout drift behind noise.
• Low-confidence findings are advisory too: they sit on a node pair that was guessed rather than matched by identity.

Fix the layer the finding names. Nudging nearby values until the numbers agree produces a screen that passes the check and drifts everywhere else.

Make the matching exact

Matching is exact when the code carries the design's node id, and heuristic otherwise:

• Web: emit the design node id as a data-pr-* attribute.
• Native: set it as the accessibilityIdentifier.

Heuristic matching still works, but it produces findings on node pairs that were guessed, and a guessed pair is where a confident wrong report comes from. If you want findings you can act on, emit the id.

Check the reference before trusting a clean report

A pass is only as wide as what it compared against. When the design is open in Studio, the reference is the whole node tree. When it is not, the reference falls back to the flow-control hotspots, which is a handful of controls rather than the screen. A clean report against the narrow reference is not the same result, so read which reference was used before calling the screen done.

Scope

• Touch only the files the task lists. If the correct fix needs another file, say so in the run summary instead of widening silently.
• A design drift fix runs on its own branch, never straight onto the default branch.
• Only a verified run may mark a code binding as synced.

What to read next

• Flows and prototypes for running the journey, not just the screen.
• Bringing a design in from Figma for what the reference is on a transferred frame.