/design-fidelity-verify

name: design-fidelity-verify
description: Prove a running app matches its design spec by measuring rendered values, not eyeballing a screenshot. Use when the user says "verify the design", "is this pixel-perfect", "check against Figma", "does the app match the design", or "design QA this screen". Runs a bounded vision+numeric loop over web or mobile, classifying every spec row rather than reporting a bare pixel delta. Consumes the figma-design-extract spec table.
license: MIT
compatibility: Requires a browser MCP (web) or a device MCP (mobile) that can evaluate JavaScript in the running app.

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`](../figma-design-extract/SKILL.md)** — 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`](references/verify-web.md) | | **Mobile** | The resolved style off the rendered React fiber, read over the Metro/CDP eval channel; capture at `scale: 1.0` | [`references/verify-mobile.md`](references/verify-mobile.md) |

Both platforms then classify each row using [`references/drift-classification.md`](references/drift-classification.md).

Runnable readers ship with this skill — [`scripts/`](scripts/). Don't re-derive them per run.

> **Tool-agnostic:** Argent, metro-mcp, agent-device, 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. The one hard requirement is a channel that can **evaluate JavaScript in the running app**.

---

The loop (same for every platform)

B0. Preflight (clear these FIRST)

**In practice most verify time goes to infrastructure gates, not the design diff** — often the large majority of it. Discovering a gate *after* a 15–20 minute native build is the dominant failure mode. Clear all five before you build or rebuild anything:

• **Environment up?** Is the backend/API the screen needs actually reachable? A failed login or an empty data screen is usually a down environment, not a code bug — don't burn a rebuild fighting it. Read the error literally: an auth error naming a bad URL is infrastructure, not a bad credential.
• **Test-data shape right?** Does the account/fixture expose what the screen needs? A component that only renders when `items.length > 1` **verifies nothing** on a single-item account — you will measure an empty screen and report a pass. Confirm the data shape before building.
• **Inspection tooling connected?** Whatever you'll use for the numeric pass (browser devtools/CDP, the app's JS-eval channel, native view introspection) — confirm it actually attaches **now**, not at measurement time. Plan the fallback if it doesn't (see your platform reference). On mobile, note that "the MCP server isn't connected" is not the same as "the tool isn't installed."
• **Build current?** A stale build verifies the wrong code. Rebuild if the bundle/entry changed. Tell-tale on RN: a red box reading "No script URL" or "Unable to resolve module ./index".
• **Authenticated?** Most real screens sit behind auth. Automate the login so re-verifies are repeatable, and keep credentials out of the transcript.

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:

`la