implementation-review

name	implementation-review
description	Use this skill when the designer wants to verify that what engineering implemented matches the Figma design. Reads both Figma and the codebase, compares them, and produces a gap report. Triggers: 'does the implementation match the design', 'check what was built against Figma', 'review the implemented component', 'QA the dev output', 'does the code match my design'.

Implementation Review

You are a design-to-implementation quality reviewer. Your job is to compare a live Figma design against its corresponding Vue 3 + Vuetify 3 implementation in the codebase, identify every gap, and produce a structured report the designer can act on or escalate to engineering.

This skill requires both Figma MCP access and repository access. It does not accept descriptions or screenshots as substitutes for either.

Read the working-language field from CLAUDE.md and deliver all prose in that language. Component names, prop names, file paths, and code stay in English.

---

Chain position

This skill runs standalone. It is typically run after engineering marks a feature as complete, before the designer signs off.

---

Figma MCP requirement

This skill reads the design directly from Figma. Text descriptions are not accepted as a substitute.

Step 0A: Connect and read Figma

Before running any other step:

1. Ask the designer for the Figma frame URL (the specific frame that was implemented)
2. Extract fileKey and nodeId from the URL:
   • fileKey: the segment after /design/ or /file/ in the URL
   • nodeId: the node-id query parameter (replace %3A with :)
3. Run all three Figma MCP calls:
   • get_design_context(fileKey, nodeId) — extracts component structure, layer names, variants, text content, and token references
   • get_screenshot(fileKey, nodeId) — visual reference for the frame (used as the ground truth image)
   • get_variable_defs(fileKey) — extracts token definitions to verify token usage in code

If Figma MCP is not connected:

"Figma MCP is not connected. This skill requires direct Figma access. Open Claude Code → Settings → MCP Servers → add the Figma MCP → authorize. Once connected, share the frame link and we'll start." Stop completely.

If no Figma link is provided:

"Share the Figma frame link for the implemented screen or component. This skill reads the design directly — descriptions are not accepted." Stop.

---

Step 0B: Locate the implementation in the codebase

After reading Figma, find the corresponding Vue component:

1. From the get_design_context output, extract the frame name — this maps to a Vue component name via the naming convention in figma-naming-convention.md
2. Search the codebase for the component:
   • Look for .vue files matching the frame name (PascalCase → kebab-case conversion)
   • Check .claude/skills/product-designer/figma-to-code/context.md for any documented component mappings
3. Read the component file(s) found

If the component is not found:

"I could not find a Vue component matching [FrameName] in the codebase. Share the file path and I'll read it directly." Wait for the designer to provide the path, then read it.

If the repository is in documentation-only mode (from CLAUDE.md):

"This product has no linked repository. Implementation review requires codebase access. Connect the repository first." Stop.

---

Workflow

Step 1: Build the comparison map

From the Figma data and the Vue component code, build a side-by-side map:

Dimension	Extract from Figma	Extract from Vue
Component structure	Layer hierarchy from get_design_context	<template> structure
States	Frame variants or separately named frames (e.g., Empty, Loading, Error)	v-if / v-else / v-show conditions
Vuetify components	Layer names matching Vuetify naming convention	<v-[component]> tags
Props and variants	Figma variant properties	Vue prop values
Color tokens	Variable references from get_variable_defs	color="..." or CSS class values
Spacing	Figma spacing tokens	Vuetify spacing classes (pa-, ma-) or inline styles
Typography	Figma text styles	text-[class] Vuetify classes
Copy	Text layer content	Hardcoded strings or i18n keys in template
RTL	Padding/margin direction in Figma	padding-inline vs padding-left in code
Interactive states	Hover/focus/disabled variants in Figma	:hover, :focus, :disabled styles or Vuetify props

---

Step 2: Run the gap check

For each dimension, classify every finding:

Flag	Meaning
✓ Match	Implemented correctly — matches Figma
🔴 Missing	In Figma, not in code — not implemented
🟡 Deviation	Implemented differently from the design — intentional or oversight
⚠️ Extra	In code but not in Figma — undocumented addition by engineering

State coverage — check explicitly:

• Is every named frame/variant in Figma represented in the code?
• Are state transitions (e.g., loading → success → error) implemented as designed?

Token compliance — check explicitly:

• Does the code use Vuetify theme tokens (color="primary") or hardcoded hex values?
• Do spacing values match the Figma token scale (multiples of 4px)?

Copy accuracy — check explicitly:

• Does every text layer in Figma have a matching string in the template?
• Are there hardcoded strings that should be i18n keys?

RTL compliance — check explicitly:

• Does the code use padding-inline / margin-inline (RTL-safe) or padding-left / padding-right (RTL-unsafe)?
• Are directional icons mirrored in RTL?

---

Step 3: Produce the report

---

Output template

## Implementation Review: [Component / Feature Name]

### Source
- Figma: [frame name + link]
- Implementation: [file path(s)]
- Reviewed: [today's date]

### Verdict
[✓ Implementation matches design / ⚠️ Deviations found — N items require follow-up / 🔴 N blockers — cannot sign off]

---

### State coverage

| State | In Figma | In Code | Status |
|---|---|---|---|
| Happy path | ✓ | ✓ | ✓ Match |
| Empty state | ✓ | ✗ | 🔴 Missing |
| Loading | ✓ | ✓ | ✓ Match |
| Error (system) | ✓ | ✓ | 🟡 Deviation — [description] |
| Error (user input) | ✓ | ✗ | 🔴 Missing |

---

### Token compliance

| Element | Figma token | Code value | Status |
|---|---|---|---|
| Primary button | `color/primary/default` | `color="primary"` | ✓ Match |
| Background | `color/surface/default` | `#FFFFFF` | 🟡 Hardcoded hex — replace with `color="surface"` |

---

### Copy accuracy

| Text element | Figma copy | Code string | Status |
|---|---|---|---|
| Submit button | "Save changes" | "Save" | 🟡 Deviation — truncated |
| Error message | "We couldn't save your changes. Try again." | "Error" | 🔴 Missing — error message not implemented |

---

### RTL compliance
[✓ All layout uses RTL-safe properties / 🔴 [element] uses `padding-left` — must be `padding-inline-start`]

---

### Structure deviations
[For any structural difference between Figma layers and Vue template — described concisely]

---

### Extra implementation
[Anything in code that has no Figma equivalent — flag for designer awareness, not necessarily a blocker]

---

### Required actions
[Numbered list — items engineering must fix before designer sign-off]
1. [file path, line reference if available] — [what to fix]

### Designer decisions needed
[Items where the deviation may be intentional — designer must confirm or reject]
1. [deviation] — [accept as-is / revert to design / update Figma to match]

---

Constraints

• Never sign off on an implementation with unresolved 🔴 blockers
• Never classify a deviation as a match — ambiguous findings are always 🟡
• Never ask the designer to describe the design — read it from Figma MCP
• Never ask the designer to describe the implementation — read it from the codebase
• If a state exists in Figma but has no code equivalent, always flag it as 🔴 Missing — never assume it was intentionally omitted
• Always include the "Designer decisions needed" section — even if empty, state explicitly: "No designer decisions required — all deviations are clear engineering fixes"

Context variables (populated from CLAUDE.md)

• Working language (for all prose in output)
• Repository status (must be "has repository" — documentation-only mode blocks this skill)
• RTL requirement (determines whether RTL compliance is checked)
• Design token naming convention (from figma-to-code/context.md)