# Reviewing Design Fidelity

> Reviews implemented UI against design source-of-truth (Figma frames, mockup images, design tokens) for visual fidelity — spacing, typography, color, responsive behavior, interaction states, accessibility. Use when comparing built pages to design specs, when a Figma URL is shared alongside a live URL/screenshot, or for "디자인 검수", "퍼블리싱 검토", "compare with figma", "픽셀 비교", "design QA", "피그마대로 되어있나", "figma vs 현재 화면", "구현이 디자인과 맞는지". Also triggers when a Figma URL is shared with reference to existing implementation. Triggers even when the change appears trivial — single label swap, one CSS rule, one-line JSX edit — because apparent simplicity is the most common skip rationalization, and the skill itself decides scope (full audit vs quick check) faster than the caller can. Captures both sides (Figma + Playwright snapshot), runs structured visual diff, reports gaps by user-visible impact. Distinct from reviewing-spec-and-policy (audits docs) and code review (audits code structure).

- Skill: `pacho-h/reviewing-design-fidelity` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add pacho-h/reviewing-design-fidelity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pacho-h/reviewing-design-fidelity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: pacho-h (https://skillmd.com/u/pacho-h)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pacho-h/reviewing-design-fidelity

---


# Reviewing Design Fidelity

## Purpose

Implementation drifts from design — silently, in small increments, every sprint. Padding shrinks by 2px to fit a label, a hex code gets approximated, a state variant is forgotten. Each drift is invisible alone; together they erode the brand and the design system. This skill performs side-by-side capture and structured comparison so drift is surfaced concretely, with evidence, before it accumulates further.

The skill produces an annotated gap report — not a redesign. It assumes the design is the source of truth and the implementation should match it; if that assumption is wrong (e.g., implementation revealed a design problem), surface that as a separate finding rather than rewriting the design.

## When to use this skill

- A Figma URL is shared together with a live URL or built page screenshot
- User asks to "verify design", "compare with Figma", "check publishing", "디자인 검수", "퍼블리싱 검토", "design QA pass"
- After a frontend feature is implemented and before sign-off
- When the design system maintainer reports drift across a release

## When NOT to use

- Reviewing the design itself (no implementation yet) → use `reviewing-spec-and-policy`
- Reviewing code structure / component APIs → use `superpowers:requesting-code-review`
- Generating new design from code → that's the figma-generate-design skill, not this one

## Workflow

### 1. Identify both sides

Before capturing anything, confirm:
- **Design side:** Figma file URL + specific frame node IDs to review (one frame per screen state, including hover/focus/error/empty if applicable)
- **Implementation side:** live URL OR a path to deployed screenshots OR a local dev server URL

If either side is missing, pause and ask. A one-sided "review" is just an opinion.

### 2. Extract the design context

For each frame:

1. `mcp__plugin_figma_figma__get_metadata` → confirm frame structure and identify variant set
2. `mcp__plugin_figma_figma__get_variable_defs` → pull design tokens (color/spacing/typography) referenced by the frame. These are the canonical values; any drift in implementation should be measured against tokens, not against rendered pixel values, when tokens exist.
3. `mcp__plugin_figma_figma__get_design_context` → structured component data + Code Connect mappings if present
4. `mcp__plugin_figma_figma__get_screenshot` → reference image for the frame

See `references/figma-extraction.md` for tactics on multi-variant frames and Code Connect interpretation.

### 3. Capture the implementation

Use Playwright MCP to capture the live page in matched viewport sizes:

1. `browser_resize` to the design's intended viewport (mobile 375, tablet 768, desktop 1440 — or match the Figma frame width)
2. `browser_navigate` to the page URL
3. `browser_snapshot` for the accessibility tree (text content, ARIA roles, heading structure)
4. `browser_take_screenshot` for visual comparison
5. For interaction states, use `browser_hover` / `browser_click` then re-snapshot to capture hover/active/focus visuals
6. `browser_console_messages` once per page — console errors during rendering are themselves fidelity findings (broken images, missing fonts)

See `references/playwright-capture.md` for state coverage and viewport-matrix patterns.

### 4. Compare across the fidelity matrix

Apply the seven dimensions from `references/fidelity-matrix.md`:

1. **Layout & spacing** — padding, margin, gap match design tokens
2. **Typography** — font family, weight, size, line-height, letter-spacing
3. **Color** — fills, strokes, text — match tokens (not just visually similar)
4. **Iconography & imagery** — correct asset, correct size, correct positioning
5. **State coverage** — hover, focus, active, disabled, loading, empty, error all implemented
6. **Responsive behavior** — design intent preserved at each breakpoint, not just "doesn't crash"
7. **Accessibility** — contrast ratio, focus visibility, semantic structure, alt text, keyboard reachability

Each dimension produces zero or more findings.

### 5. Prioritize by user impact

- **Critical** — broken or unusable (missing state, content overflow that hides info, accessibility blocker)
- **Major** — visibly wrong (color/spacing off enough that a designer would call it out, missing variant)
- **Minor** — token drift not visually detectable but breaks design-system contract (e.g., 14px instead of token `text-sm`/15px)

Skip subjective preference findings ("I'd prefer more whitespace"); only flag drift from the documented design.

### 6. Produce the report

Use the structure in `references/fidelity-report-template.md`. Each finding includes:
- Frame reference (Figma node ID)
- Implementation reference (URL + viewport)
- Side-by-side evidence (screenshot paths or quoted token values)
- Dimension category
- Priority
- Concrete fix suggestion (token name, CSS property, or component prop change)

When the report leads to an actual PR, embed the captured screenshots in the PR body — text-only fidelity reports lose their evidence the moment the temp screenshot files are deleted. See `references/fidelity-report-template.md` § "Embedding evidence in PRs".

### 7. Hand off to the next skill

A fidelity review often surfaces gaps that aren't fidelity gaps — empty/error states missing entirely, API contract drift, no integration coverage for the BE change you just discovered. Don't fix them silently inside this skill — invoke the right next-step skill so the work stays auditable. See `references/skill-handoff.md` for the trigger matrix.

## Principles

- **Tokens first, pixels second.** A 14px font-size when the design token is `text-sm` (15px) is a finding even if visually indistinguishable — the design system contract is what gets re-rendered when tokens change.
- **Capture all states, not just the default.** Most drift hides in hover/focus/error/empty states because those rarely appear in a happy-path design review.
- **Match viewports.** A "looks fine on my laptop" review misses the 70% of users on other viewports. Capture each breakpoint in the design.
- **Evidence is required.** Every finding must reference a captured artifact (screenshot, snapshot tree, console log, computed style). "It looks off" without artifact = not a finding.
- **Distinguish drift from design conflict.** If implementation reveals a design problem (e.g., text actually overflows in real content), that's a separate finding flagging the design — don't try to silently "fix it" in implementation.

## Detailed references

- `references/figma-extraction.md` — tactics for multi-variant frames, Code Connect mappings, and choosing which frames to review
- `references/playwright-capture.md` — viewport matrix, state-capture **checklist**, console-error interpretation
- `references/fidelity-matrix.md` — full descriptions and example findings for the seven dimensions
- `references/fidelity-report-template.md` — annotated template with example findings showing artifact references, plus PR-embed guidance
- `references/skill-handoff.md` — when to invoke `improving-feature-completeness`, `running-integration-tests`, or `reviewing-spec-and-policy` from a fidelity review