ui-dev:figma-implement

What this skill does

# Figma UI Implementation

Trace prototype graph to plan all screens, then implement one screen at a time with subagent-driven implementation and review.
The parent acts as an orchestrator, delegating implementation and review to subagents.

## Prerequisites

- Figma designs are marked as Ready for Dev
- Working branch is isolated via git worktree (recommended)
- Anthropic official Figma plugin is installed

## Injections

- `!.agents/ui-dev/$ARGUMENTS/config.json` — existing config (resume if present)
- `!git worktree list` — worktree status

---

## Phase 1: Preparation (only if config.json does not exist)

If config.json already exists, skip to Phase 2 and resume. Resume position is determined by the state of the reports/ directory:

- No `{screen}-implement.md` → Start from Step 1 (implementation)
- `{screen}-implement.md` exists but no `{screen}-visual-review.md` or `{screen}-code-review.md` → Start from Step 2 (review)
- Review reports exist, `{screen}-fix-{N}.md` is the latest (no corresponding re-review) → Start from Step 2 (treat fix-N as the implement report)
- Review reports exist, no fix → Start from Step 3 (auto-classify and fix if needed)

### Step 1: URL Parsing

1. Extract flow name and Figma URL from `$ARGUMENTS` (e.g., `registration https://figma.com/design/...?node-id=xxx`)
2. Extract fileKey and nodeId from the URL
3. Create artifact directories:
   - `.agents/ui-dev/{flowName}/`
   - `.agents/ui-dev/{flowName}/screenshots/`
   - `.agents/ui-dev/{flowName}/reports/`

### Step 2: Prototype Graph Trace + Screenshots

```bash
${CLAUDE_PLUGIN_ROOT}/skills/figma-data/scripts/trace-prototype-chain.ts \
  --file-key <fileKey> --node-id <nodeId> \
  --output .agents/ui-dev/{flowName}/prototype-chain.json
```

BFS-traverses the prototype graph and automatically saves PNG screenshots for all discovered frames to `<output-dir>/screenshots/`. Screenshot paths are recorded in the graph JSON under `frames[id].screenshot`.

Check the frame count and JSON path. If only 1 frame, confirm with the user whether the start node is correct.

Use `query-prototype-chain.ts --json-path <path> --node-id map` to view the full page map with all frame connections — useful as a reference when creating the screen map.

### Step 3: Create Screen Map (All Screens)

Create a screen map based on the prototype chain:

1. Generate `.agents/ui-dev/{flowName}/screen-map.md` from the screen map template
2. Fill in all screen information (transitions, states, validation, etc.)
3. Confirm with the user; mark unclear items with `⚠️ Unconfirmed`

Screen map template: @${CLAUDE_PLUGIN_ROOT}/skills/figma-implement/references/screen-map-template.md

### Step 4: Generate config.json

```json
{
  "flow": {
    "name": "{flowName}",
    "currentPhase": "implement",
    "figma": {
      "fileKey": "{fileKey}",
      "prototypeChainPath": ".agents/ui-dev/{flowName}/prototype-chain.json"
    },
    "screens": ["{screen1}", "{screen2}", "..."]
  },
  "contextFiles": [],
  "reviewPrompts": {
    "common": [],
    "visual": [],
    "code": []
  }
}
```

Suggest customizing `reviewPrompts` and `contextFiles` (files to reference during review, e.g., design system documentation).

---

## Phase 2: Implementation Loop

### Critical Rules

- **The parent is an orchestrator ONLY.** The parent MUST NOT write any implementation code itself. ALL implementation and review work MUST be delegated to subagents via the Task tool
- **Do not ask the user for confirmation at each step.** Complete all screens autonomously and report the results at the end
- **All review findings must be addressed** — fix every issue reported by reviewers. If a finding cannot be fixed via code (spec ambiguity, design issue, architecture concern), record it as a TODO and move on
- **Interactions are mandatory.** Every screen's transitions, animations, and interactive behaviors from the prototype chain and screen map MUST be implemented. Skipping interactions is not acceptable

```
for (screen in screens) {
  1. Spawn implementation subagent (via Task tool) -> write to report
  2. Spawn review subagents in parallel (via Task tool)
  3. Auto-classify findings and spawn fix subagent (via Task tool) if needed -> return to 2
  4. When no fixable findings remain, move to next screen
}
```

### Step 1: Spawn Implementation Subagent

Spawn via the Task tool. See `@${CLAUDE_PLUGIN_ROOT}/agents/implementer.md` for the agent definition, input/output format, and report structure.

When the subagent returns, **read the report file** to get information. Do not use the subagent's return text. If the report does not exist, restart with the same prompt once. If it fails twice in a row, report to the user.

### Step 2: Spawn Review Subagents (Parallel)

Read the implementation file list from the report and spawn two review agents **in parallel** via the Task tool.
See `@${CLAUDE_PLUGIN_ROOT}/agents/visual-reviewer.md` and `@${CLAUDE_PLUGIN_ROOT}/agents/code-reviewer.md` for review agent definitions.

If one review agent returns without writing a report, restart only that agent once. If both fail, report to the user.

### Step 3: Auto-Classify and Fix

Read both review reports and auto-classify findings. **Do not ask the user for judgment.** Address all findings autonomously:

#### Issue Classification Guide (A/B/C/D)

| Category                          | Description                                                | Action                                                                     |
| --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| **A. Fixable via code**           | Bugs, style mismatches, missing implementation             | Fix -> re-run Step 2                                                       |
| **B. Spec ambiguity/gap**         | Undefined retry limits, missing timeout handling, etc.     | Make a reasonable assumption, fix, and record the assumption in the report |
| **C. Design change needed**       | Undefined error states, layout breaks with real data, etc. | `// TODO(design):` + mark screen map with `⚠️ Unconfirmed`                 |
| **D. Architecture change needed** | State management rethink, API call timing change, etc.     | Record in "Unresolved TODOs" in the report                                 |

- **A and B findings**: Spawn fix subagent to address all of them. All reviewer findings must be fixed
- **C and D findings**: Record as TODOs and proceed (these require human decisions)
- **No fixable findings (A/B)**: Screen passes. Go to Step 4

### Step 4: Spawn Fix Subagent

Spawn a new subagent in fix mode. See `@${CLAUDE_PLUGIN_ROOT}/agents/implementer.md` for fix mode details.

If the fix subagent returns without writing a report, restart once (same as implementation subagent).

After fix completion, return to Step 2. Re-reviews overwrite the same filenames (`{screenName}-visual-review.md`, `{screenName}-code-review.md`).

If the fix loop exceeds 3 iterations for the same screen, record remaining findings as TODOs and move to the next screen.

### Step 5: Move to Next Screen

Move to the next incomplete screen and return to Step 1.

### Screen Pass Criteria

- No critical visual diffs in visual-review (or all addressed)
- No missing transitions or states in code-review (or all addressed)
- Any unresolvable items are recorded as TODOs + in the screen map

---

## Phase 3: Completion

When the implementation loop completes for all screens:

1. Update config.json `currentPhase` to `"done"`
2. Present a **comprehensive completion summary** to the user, including:
   - List of all implemented screens and their status
   - All fix iterations performed per screen
   - All remaining TODOs (categorized by C/D type)
   - Any assumptions made during B-type fixes

This is the only point where the user receives a full report. Make it thorough.

---

## Directory Structure

```
.agents/ui-dev/