design-fidelity-verify

Design Fidelity Verify — prove the running app matches the spec

"Looks done" is not a check. This skill runs a measured feedback loop: render → capture → read the actually rendered values off the live app → compare each against the design spec → fix → re-verify, bounded. The numeric pass is the whole point — it catches what the eye and a screenshot cannot. The bar is spec fidelity — every value resolves to its intended token, within tolerance — not literal "pixel-perfect" (a phrase that means little across devices); measure tokens and deltas, don't chase byte-identical pixels.

Upstream: the spec table

This skill consumes the design-spec table produced by figma-design-extract — rows of element | property | exact value | repo token | source component. If you don't have one yet, run that skill first. The spec is your pass/fail checklist; without it you're back to eyeballing.

Why this exists (two failure modes)

1. Blurry capture. The default device/headless screenshot is often low-res and hides truncation, wrong colors, and small spacing drift. Always capture full-resolution.
2. No feedback loop. Building once and declaring victory is not verification. Render → measure → compare → fix → re-measure, with a hard cap so it terminates.

When to use

Trigger phrases: "verify the design", "is this pixel-perfect", "check against Figma", "does the app match the design", "design QA this screen", or immediately after building a screen with figma-design-extract.

---

Pick your platform (then load the matching reference)

The loop below is identical for web and mobile. Only two steps differ — how you capture full-res, and how you read rendered values. Read the one reference file for your platform before the numeric pass (B5); ignore the other.

Platform	Capture + measure mechanics	Reference to load
Web	getComputedStyle + getBoundingClientRect via a browser/Playwright/Chrome MCP; capture at devicePixelRatio ≥ 2	references/verify-web.md
Mobile	Native view props (backgroundColor, bounds, cornerRadius, font) via Argent or similar, captured at scale: 1.0	references/verify-mobile.md

Tool-agnostic: Argent, agent-device, an iOS-simulator MCP, Playwright, Chrome MCP — any of them works. The reference files name specific tools as examples; what matters is that you read the rendered value, not that you use a particular MCP. Adapt to whatever you have connected.

---

The loop (same for every platform)

B0. Preflight (clear these FIRST)

In practice most verify time goes to infrastructure gates, not the design diff — and each one discovered late wastes a rebuild. Check before building/rebuilding:

• Environment up? Is the backend/API the screen needs actually reachable? A failed login or empty data screen is often a down environment, not a code bug — don't burn a rebuild fighting it.
• Test-data shape right? Does the account/fixture expose what the screen needs (the multi-item case, the specific state)? A component that only renders when items.length > 1 verifies nothing on a single-item account. Confirm the data shape first.
• Inspection tooling connected? Whatever you'll use for the numeric pass (browser devtools/CDP, native view introspection) — confirm it actually attaches now, not at measurement time. Plan the fallback if it doesn't (see your platform reference).
• Build current? A stale build verifies the wrong code. Rebuild if the bundle/entry changed.
• Authenticated? Most real screens sit behind auth. Use your app's login flow and automate it if you can, so re-verifies are repeatable.

B1. Run, navigate, and record the path

Build/run the app and navigate to the screen. Record the navigation as a replayable flow so every re-verify is identical — no interaction variance between iterations. (See your platform reference for the recording mechanism.)

B2. Capture full-resolution

Capture the screen at full resolution (web: dpr ≥ 2; mobile: scale: 1.0). Low-res capture is failure mode #1 — do not skip the resolution bump.

B3. Map on-screen elements → code

Get the element tree with names + coordinates, so when something is off you can jump straight from the on-screen position to the file:line that renders it instead of hunting.

B4. Vision pass

Place the app capture beside the Figma reference (get_screenshot from the extract step). Enumerate discrepancies by category so nothing is hand-waved:

layout/alignment · spacing · color · typography · radius · sizing · states/icons · missing/extra elements

B5. Numeric pass (the rigor)

Read the actually rendered values off the live app and compare each against the spec table. Read your platform's reference file now (references/verify-web.md or references/verify-mobile.md) for the exact calls — the discipline is the same:

• Pull the rendered value (computed style on web; native view prop on mobile).
• Walk every row of the spec table: spec value vs measured value → PASS / FAIL + delta.
• Degrade gracefully, don't skip. If one measurement channel is blocked (e.g. native color read won't attach), fall back to what is measurable (bounds/placement/sizing from the element tree) and record the rest as an explicit residual — "hex not measured: introspection unavailable" — rather than silently claiming a full pass.

B6. Discrepancy report

element  | property | spec     | app      | delta   | severity
---------+----------+----------+----------+---------+---------
CTA      | bg       | #00B140  | #00A038  | off     | high
Row gap  | gap      | 8        | 12       | +4      | med
Title    | weight   | 600      | 400      | -200    | high

B7. Fix + re-verify (bounded)

Fix highest-severity first → replay the recorded flow → re-capture → re-run the numeric pass. Tokenize every value you touch while fixing — never paste a raw hex/px to "make it match"; that just reintroduces drift. Hard cap: ~3 iterations. Then stop and report what remains. Unbounded loops cause context rot and undo-fixes.

B8. Optional clean-context review

For a high-stakes screen, spawn a fresh review subagent to run B4–B6 without the implementer's bias.

B9. Optional — lock in a regression baseline

The numeric pass proves a first build matches the spec; visual-regression tools can't do that (they need a prior approved render to diff against). Once it passes, snapshot the screen as that baseline so a VR tool (Playwright toHaveScreenshot, Chromatic, Percy, Applitools) catches future regressions the one-shot numeric pass won't. Complementary: numeric diff for first-build conformance, VR for ongoing protection.

---

Guardrails

• Never report "matches the design" without the numeric pass (B5). A clean vision pass alone is not proof.
• Never measure from a screenshot — either side. Screenshots catch "wrong thing built", not "4px off".
• Always capture full-res (web dpr ≥ 2 / mobile scale: 1.0). The default is usually too blurry to trust.
• Cap the loop at ~3 iterations and report residuals honestly rather than thrashing.
• Record the navigation as a flow so each re-verify measures the same screen state.