Implement a Figma design with UI Verify (the design is the source of truth)

You are building a page/component in code to match a design image (a Figma export or mockup screenshot).
UI Verify sets that image as the story's baseline, renders your story in its own browser, diffs it against
the design, and hands you back the delta. You converge until the delta is gone, and stop there. You do
NOT accept - accepting would rebase the baseline off the design (see "Do not accept" below).

The flow: get the design PNG -> declare it as the story's baseline -> build the whole page once -> then
sweep top-to-bottom, locking one section at a time -> stop at the minimum. Every round renders only the
story you are building (uiverify check --target), never the whole Storybook.

Read "The section sweep" below before your second upload. It is the whole method. Four previous agents
failed this task, all in the same way: they treated convergence as tuning a number instead of locking
sections, and all four stalled between 2.5% and 5% and declared a floor that was not a floor.

Evidence integrity

These qualifications apply to the sweep and the historical examples below:

• Record the commit, build ID, diff ID, baseline image hash, candidate image hash, dimensions, and mask

• metrics.changedPct is a fraction. Display 100 changedPct followed by %, alongside changed

This is not advice, it is the loop you run. It is how a person would do it with the design and the render
side by side: "Does the very top look right? No - fix, fix, fix, upload, look again. Yes? Good, I never
touch it again. Next block down. Does it look right? ..." all the way to the bottom.

• Before round 2, write the block list. Split the design at its real whitespace boundaries into blocks

  git add -A && git commit -qm "attempt N: <block>: <change>"
  npx storybook build -o storybook-static   # or your repo's build script
  UIVERIFY_API_KEY=uv_proj_... npx -y uiverify@latest check --static-dir ./storybook-static --target 'pages-profile--default'

The story id is in storybook-static/index.json (a target that matches nothing fails the check and
lists the valid ids). For a design with several frames (desktop and mobile stories), pass --target
once per story, or one glob over just that component ('pages-profile--'). Never uiverify upload
the whole Storybook per round: it re-renders every other story in the project (every button variant,
every unrelated page) each time, so each round waits on renders that say nothing about the design. A
check still diffs against the declared design, posts no GitHub check, and never moves a CI baseline; the
full uiverify upload runs in CI on the pull request.

THE RULE - UI Verify is the only source of truth

• *All diffing is done by UI Verify, through the native mcp__uiverify__ MCP tools. Never compute

• No private measurement loop. Never serve storybook-static yourself, never open your page in

• You MAY measure sizes and positions with Python/PIL - on the design PNG, and on the

• The changed-% is a progress log, NEVER a decision input.* It is one area-weighted scalar over the whole

Why top-down is not just tidy: in ordinary flow layout a height/gap fix in section k moves sections
k+1…N and usually leaves everything above it alone, so sweeping downward keeps most of what you finish
finished and gives you a simple reading of inherited drift: if everything above section k is locked and
section k's contents are uniformly N px off, the first suspect is the gap immediately above this
section, not the elements. It is a heuristic, not a guarantee - a shared style, a font-size change on a
reused class, or a width change that re-wraps text can reopen a block above. When a fix touches anything
shared, re-fill the tables of the blocks that depend on it.

The loop:

• Identify the current section's own pixel bounds in the design - nav, hero, logo strip, card row, CTA

• Fix all of them. Batching within one section is fine and correct - the fixes are co-located and you

Budget: locking a 2000px page is ~7 sections, and ~2 uploads per section is the floor of effort, not a
target you stop at. You have a 50-upload budget overall and 15 per block (see "The algorithm") -
spend it driving each block to zero rows, not stopping the moment the overlay looks calm. Under-using the
budget is how runs stall: the last three stopped at uploads 30, 25 and 23 with measurable geometry still on
the page.

Anchor in absolute design coordinates

The strongest technique available to you: measure the design once to get the absolute y of every section
boundary (and the absolute x of every column), then measure the same anchors in your candidate and solve
for the property.

> design divider is at y=1810; my CTA bottom is at 1748 and my current margin is 29, so I compute 1777;
> to hit 1810 I need margin-top = 62.

That is a derivation, not a guess. Do this instead of nudging.

But it only works top-down and one section at a time. That arithmetic is a chain: if you also change
something above the CTA in the same round, the CTA bottom moves and your footer number is already wrong
before it lands. A previous run computed exactly the footer margin above, changed the card padding in the
same upload, and went 3.42% -> 4.72%.

And match each section's OWN HEIGHT, not only where it lands. Absolute anchors alone can be satisfied
by cancelling errors: a card row 15px too tall plus a margin below it 8px too small, a preview band 11px too
short plus a gap 12px too big. Every later section lands at roughly the right y, the overlay looks calm, the
% stays low - and the structure is wrong. For every section check top, bottom AND height against the design.

sizeChanged: true means you are not done. If the candidate's height differs from the design's, some
section's height is wrong. Keep going - never treat it as done.

The overlay lies about low-contrast edges

which:"diff" highlights per-pixel differences above a threshold (often ~0.06). A low-contrast element -
a near-white pill on white, a pale card fill, a light divider - can be displaced by tens of pixels and still
not trip the threshold, while the dark text inside it lights up green.

The overlay then tells you the exact opposite of the truth: "the box is fine, only its text moved." In one
run a badge pill was 35px too wide (12%) and showed zero highlight on its outline; the agent read the
clean outline as proof the pill was correct and called the green text "AA fringe".

Therefore: never judge a section from the overlay alone. Always also read baseline and candidate at
the same window. A box that looks clean in the overlay can be the most wrong element on the page.

Measure, do not eyeball

Eyeballing produces "the buttons look a bit off", which leads to nudging. Measuring produces "+3px tall,
+9px wide", which leads to a padding fix. Pull spans out of the images with a script:

• horizontal extent of a text run -> its rendered width -> font-size / letter-spacing
• vertical extent of a row -> its height -> padding / line-height / font-size
• row tops down a list -> the pitch between lines. A constant offset on every row is a block

Work out which dimension is wrong before changing anything:

• Element at the right position but the wrong WIDTH (box and text both scaled) = a text metric:

If a fix does not work, change DIMENSION, not magnitude. Both failed runs got stuck turning the same
knob harder. One saw the two hero buttons differ, decided the gap between them was wrong, tried 16->20px,
saw the number rise, and concluded "sub-pixel artifact". The buttons were in fact 3px taller and 9px wider -
a padding bug it never tested, because it never left the "gap" hypothesis.

Measure INK, not boxes (the last mile: sub-pixel position and weight)

Bounding boxes round to whole pixels, so they go blind exactly when you get close. A header run stalled at
0.90% because every element's bbox was "within 1px" - it called that the AA floor. It was not. Whole-pixel
bboxes cannot see the two things that dominate the last mile, and a switch of measurement (not effort) took
it 0.90% -> 0.125%, a 7x drop, all real fixes:

• Sub-pixel position. A block 0.3px off, or a group 0.7px off, rounds to the same bbox yet paints a real

• Ink density = weight or size, not position. An element dead-on in position can still be ~10% too heavy.

The rule: when every bbox reads "within 1px" but the window still lights up, your ruler is too coarse -
switch to centroid+ink (with correct foreground segmentation) before you conclude anything. The
gain comes from a sharper
measurement, not from turning a knob harder (which is the number-chasing trap).

Validate sub-pixel experiments. Compare the UI Verify candidate images or their pixel-content hashes;
an unchanged changed-pixel count does not mean the images are identical. Establish whether a fractional
CSS adjustment affects this element in this capture environment rather than assuming universal snapping.
Neither an unsuccessful adjustment nor matched centroid/ink proves cross-engine AA. Keep an unexplained
residual unresolved, and use the final visual sweep to catch shape, wrapping, border, and spacing errors.

Slice sizes

Cap pxPagination.height at ~400. A page-tall slice averages everything into a grey wash where real
geometry is indistinguishable from anti-aliasing. One run paged at height: 1019, looked at the result, and
wrote "the page is now dominated by thin AA fringe" - at that zoom, a 13px footer displacement and a 35px
pill error both look like fringe. It then accepted.

The element table (the artifact that replaces "looks fine")

For the block under the cursor, produce this table every time you read the pair. It is the only form of
"looks fine" you are allowed:

| element | design x0-x1 / y0-y1 | render x0-x1 / y0-y1 | dW | dH | dx | dy | colour D / R | centroid / ink | fix |
|---|---|---|---|---|---|---|---|---|---|

One row per text run, box, pill, icon, divider, image edge. Measure with PIL on the two PNGs UI Verify
returned (bbox by a threshold that suits the background - dark pages need >40, not <170; centroid and
ink for rows already at 0). The table goes in the round log verbatim, and the report is built from these
tables and nothing else.

What the table stops you from doing: writing "footer within 1px" next to a row that says +17. One run's
final explanation attributed a footer tagline to "cross-engine AA"; the row reads dW=+17 (font-size).
Another explained a row of small footer links as "small low-contrast text trips the threshold"; the row
reads dW=+19, dx=-10, colour 138 vs 61. Neither builder had a table, so the sentence won.

You may use the words "cross-engine AA", "baseline snapping", "rasterizer", "threshold noise" or "floor"
for an element only when its row is 0/0/0/0, its colour matches, its centroid is within 0.3px and its ink
within 3% - and you cite that row. Anything else is a fix you have not made yet. Two corollaries:

• A lit outline is always real. The overlay thresholds per pixel, so it can only under-report; it never

• A small decrement is not a stop signal. "Each remaining fix moved the number by only hundredths" is the

The stop test (this is a test, not a feeling)

A section is done when, reading baseline and candidate at that window, no element appears as a
displaced second copy, and no box differs in measured width or height. "It looks like AA now" is not a
stop test - it is the sentence every failed run wrote just before quitting.

Bbox-clean is necessary but NOT sufficient. Whole-pixel bounding boxes are blind to sub-pixel position and
to ink density (weight/size). If every box reads "within 1px" but visual discrepancies remain, investigate
further with a valid centroid+ink pass ("Measure
ink, not boxes") on each element before you declare a floor. A header that stopped at 0.90% this way had a
+9% wordmark weight, a 5deg-un-rotated logo, and two sub-pixel offsets still on it.

The page is converged only when every section passes the stop test, sizeChanged is false, required
assets are present, ignored content has the agreed scope, and the final original-image sweep has no
unresolved visual defects. Record any supported rendering tolerance and its evidence. There is no fixed
AA percentage that proves this. Stop and report the final changed-% without accepting. Otherwise continue
within the budget, or report incomplete with the remaining discrepancies and any missing dependencies.

Do not accept - it rebases the baseline off the design

Never call accept_build (or review_diff with an accept) on this task. UI Verify diffs against the
design only while the design is the baseline. Accepting replaces the baseline with your render (accepting
a check build does it too, for every later check on the branch), which (a)
hides every remaining design delta forever and (b) makes every later upload diff against your render, not the
design. A prior run accepted at ~2.8%, then a fresh session re-uploaded against that accepted render, saw
~13% "drift", and spent 20 rounds polishing a phantom against its own snapshot instead of the design. Leave
the build changed at its floor - that is the finished state, and it keeps the project reusable without
recreating it.

Confirm you are still diffing the DESIGN, every round. get_diff must report hadBaseline: true, and
render_diff_image which:"baseline" must still show the design, not an earlier render of yours. If either
fails, STOP and tell the user - the branch was accepted or the baseline failed to resolve, and the number
is now measuring your render against itself.

The MCP tools you use (UI Verify)

Use the native mcp__uiverify__ tools - they return inline images you read directly. If they
are not available in your session, stop and tell the user. Do not fall back to curl against the MCP
endpoint: the MCP connects at session start, and the fix is connecting it and starting a fresh session.
(Downloading the PNG URLs that get_diff returns is fine - that is how you measure.)

• get_build { buildId } - the build's changed stories, each with a diffResultId and changedPct.

• Batching fixes across sections, so a regression cannot be attributed. (3.42% -> 4.72%, run stalled.)
• Letting the number veto a correct diagnosis. One run wrote "footer link spacing is ~2px/line too

• Bisecting margins against the scalar ("the midpoint between rounds 15 and 16"). Eleven rounds, 0.3

• Declaring an "AA floor" from a page-tall slice, or from the overlay alone.
• Declaring an "AA floor" from whole-pixel bounding boxes, before an ink-centroid pass. Every box "within

• Stopping at a low flat number instead of at true convergence or 50 uploads. 1.09% with a default UA

• Substituting URLs or the diff overlay for inspecting original baseline/candidate pixels.

• Writing a report from memory / impression instead of the per-round measurement log, so it claims work

• Moving the cursor up, or ranking blocks by changed pixels and jumping around. One run's rounds

• Declaring a block "locked" at "within 1-4px". Those pixels are the residual you later call AA.
• Leaving a measured error because "it would cascade". Recompute the intended downstream

• Stopping because the decrement got small ("only hundredths per fix"). That is the number deciding.
• Explaining a non-zero row as cross-engine AA / baseline snapping / threshold noise. Both recent runs

• Accepting at all - it rebases the baseline onto your render and poisons every later upload (a prior

• Hiding a wrong section height in the margin below it so sizeChanged looks false while the structure

• Measuring your own served page / DOM instead of UI Verify's candidate.
• Looking at the diff once and then iterating on the number plus screenshots of your own page.
• Uploading the whole Storybook every round with uiverify upload. One run re-rendered 16 stories per

• Misreading a headline halo as a missing font-weight and quitting at a plateau.