Internal SOP

Writing a design gap report.

The method used to put the PayWise Kiosk report together — turning "this doesn't match the design" into a report a developer can act on without a call. Follow this when handing off any UI discrepancy: kiosk, app, or web.

Owner: Pablo Esparza Jiménez Based on: PayWise Kiosk UI audit

Use this when

  • A built screen doesn't match its Figma design and you need to hand the gap to a developer who wasn't in the room
  • There are several screens with the same recurring issue, not just one
  • Words alone ("make it bigger", "move it up") have already failed to get the fix right once

Skip this when

  • It's one screen, one obvious fix — just say it in the thread
  • You're still deciding what the fix should be — sketch it out with the developer live first

What you need

Live productScreen recording or photos of every screen in the flow, in order
Figma fileThe design the product should match, at the real screen proportions
FigCraft (or Figma)A canvas to lay screenshots side by side and draw on top of them
Claude CodeTo pull the canvas apart and build the shareable report
01

Capture every screen in the flow

Walk the actual product end to end — phone video or screen recording is fine — touching every screen a customer would see, start to finish. Don't skip steps because they "look fine"; you want the full set to compare against, not just the ones you already suspect are wrong.

02

Build one row per screen: Current → Sketch → Design

In FigCraft (or a Figma page), paste each screen's photo into its own row, left to right:

Current — the raw photo, untouched
Sketch — same photo, marked up with the fix
Design — the matching Figma frame, screenshotted

If one screen needs more than one note, add extra sketch columns rather than cramming everything into one — a modal's overall position and its internal spacing are two different sketches, not one.

03

Mark up the sketch by hand

Draw directly on the current-state screenshot — circle the element, arrow where it should move, box the area that should expand. Keep it to one colour (red works) so it reads instantly as "this is the note," separate from the UI itself.

This is the step that makes the report land: a developer trusts a circle drawn on their own build's screenshot more than a paragraph describing it.

04

Separate what's wrong on one screen from what's wrong everywhere

Before writing anything up, sort your notes into two piles:

Screen-specific — only shows up on that one screen (a modal's padding, a missing icon on one form).

Cross-cutting — the same issue repeats across most or all screens (everything sits too low, nothing is scaled to the real screen size). These go at the top of the report, once, instead of being re-explained on every row.

05

Hand the canvas to Claude Code to build the report

Share the FigCraft/Figma file, any source video, and the Figma link. Ask for a single-page report: cross-cutting notes first, then one section per screen showing the three columns in order, each with a one-line caption — nothing more.

Say explicitly that the screenshots should carry the argument — no invented diagrams, percentage call-outs, or synthetic "before/after" graphics layered on top. If a point needs more than the photo and a sentence to land, that's a sign the sketch needs a clearer mark-up, not a better write-up.

Prompt to reuse
Build a design-gap report from this FigCraft file [+ video + Figma link]. Each row is one screen: current screenshot, my hand-marked sketch, Figma design. Use the screenshots as-is — no added diagrams or synthetic overlays. Put anything that repeats across multiple screens in a short section at the top; everything else goes in its own section per screen with a one-line caption. Plain, functional layout — this is a dev handoff, not a pitch.
06

Write every note as a request, not a correction

The developer built what the spec implied, with the information they had. The report is asking for a change, not pointing out a mistake — even when a screenshot makes the gap obvious. Pass on the wording below once, so it doesn't need re-explaining on every pass.

Instead ofWrite
"It should sit right under the header instead.""We'd like to move it up so it sits right under the header."
"This is missing / this is wrong.""We'd like to add…" / "Can this be done?"
A paragraph explaining why it's broken.One line naming the change, and let the sketch show the why.
07

Publish, share, and keep the link open for revisions

Publish as a shareable link rather than a static export — the first draft rarely survives contact with a second read. Expect a few rounds: a screenshot gets swapped, a line gets reworded, a link gets added. Update the same link each time rather than sending a new one, so whoever you handed it to is never looking at a stale version.

Do / don't

Do

  • Use the real screenshot, hand-marked, as the primary evidence
  • Keep captions to one line — the picture does the explaining
  • Group repeat issues once, at the top, instead of per screen
  • Frame every note as something you'd like changed
  • Walk every screen in the flow, even the ones that look fine

Don't

  • Let Claude invent diagrams, dashed zones, or schematic overlays to "explain" the gap — it reads as generated, not reviewed
  • Write a paragraph where a circled screenshot would do
  • Phrase a note as "this is wrong" when "we'd like this changed" says the same thing
  • Re-explain the same cross-cutting issue on every single screen
  • Send a new link every revision — update the one you already shared