# design-check - Phase 3.2-3.4 matching and comparing

## 3.2 Auto-match

For each captured screen, resolve its Figma frame: drill the relevant board (the `get_metadata` result from Phase 2), match by structure/content, and accept only a confident match. Matched → `pairs[]`.

## 3.3 Batch-ask mechanics

Collect all captures with no confident match into one list. For each, render/attach its captured PNG so the user sees exactly which visual is meant, name the screen, and ask for the Figma node-id / URL in `outputLanguage`. Optionally list best-guess candidate frame names. Each answer becomes a confirmed pair.

## 3.4 Compare call

For each pair (matched + user-supplied), fetch `get_screenshot` + `get_design_context`, then:

```
mcp__multi-agent-toolkit__design_visual_compare({
  figma_png, live_png, out_dir: "<report dir>/assets", label: "<variant>",
  figma_spec, live_geometry, figma_frame, live_screen,
  crop_top_live: <status-bar px>,       // strip device chrome the Figma frame lacks
  tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0 })
```

Collect `findings` (spacing / size / position in px, color ΔE with hex, typography), `perceptualPct`, and the written image paths (figma / live / diff / overlay / side-by-side).

## Region alignment for sheets, modals and partial overlays

Their Figma frame covers only the sheet, while the capture is the whole screen. Passing that pair as-is stretches a full screen onto a sheet-shaped frame, which misplaces every element inside the sheet and buries the real defect in noise. So for any capture whose frame is not full-screen:

```
mcp__multi-agent-toolkit__design_visual_compare({ ...as above,
  live_region:     <the sheet container's {x,y,w,h} from design_ui_geometry>,
  expected_region: <where the design puts that sheet, same units> })
```

- `live_region` rebases the comparison onto the sheet's own box. Take it from the `design_ui_geometry` element that is the sheet container (the outermost element whose height is well under the screen's and which holds the sheet's content), never from a guess.
- `expected_region` comes from the Figma frame's own placement inside its parent screen frame. With it, the engine emits an `inset` finding per edge.
- `crop_top_live` is ignored when `live_region` is given - the region crop has already excluded device chrome.

A design that shows a sheet flush to the screen edges is not satisfied by one floating in from them, and the reverse is equally wrong. The sheet's internal content padding is measured by the normal element pairing once the region alignment is right.

## Component reference and fix prompt

- **Component reference (best-effort)**: if a Figma atom carries a Code Connect component name and the repo has a matching `*.figma.swift` / `*.figma.kt`, attach that component's reference render to the variant's `componentRefs`.
- **Fix prompt**: from the findings, compose a ready-to-paste developer prompt (target file/screen + each deviation with expected vs actual token/value) so the user can hand it straight to an agent to apply the fix.