Figma2proto

---
name: figma2proto
description: Fetch Figma design via API and generate a complete design deliverable — prototype HTML, design system, design philosophy, interactions, and copy guide. Supports web, mobile, and desktop platforms.
argument-hint: '[--mobile|--desktop] <Figma URL(s)>'
disable-model-invocation: false
allowed-tools: Task, Read, Glob, Grep, Write, Edit, Bash(python3 scripts/*), WebSearch, WebFetch, Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — figma2proto

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Purpose

`/uiux` creates designs from scratch (PRD → design philosophy → design system → prototype).
`/figma2proto` starts from an existing Figma design and produces the **same complete set of outputs** — prototype, design system, design philosophy, interactions, and copy guide — so the downstream pipeline (`/implement`, `/review`, `/ship`) works identically regardless of which skill was used.

**The Figma design is the source of truth.** This skill describes and supplements it, never contradicts it.

## Output Summary

| Platform | Prototype | Design System | Other Docs |
|----------|-----------|---------------|------------|
| web (default) | `prototype/` | `docs/design_system.md` | `docs/design_philosophy.md`, `docs/wireframes.md`, `docs/interactions.md`, `docs/copy_guide.md` |
| `--mobile` | `prototype-mobile/` | `docs/design_system_mobile.md` | `docs/design_philosophy.md`, `docs/wireframes_mobile.md`, `docs/interactions_mobile.md`, `docs/copy_guide.md` |
| `--desktop` | `prototype-desktop/` | `docs/design_system_desktop.md` | `docs/design_philosophy.md`, `docs/wireframes_desktop.md`, `docs/interactions_desktop.md`, `docs/copy_guide.md` |

`docs/design_philosophy.md` and `docs/copy_guide.md` are shared across platforms.

## Prerequisites
- `FIGMA_TOKEN` environment variable (Figma → Settings → Account → Personal access tokens)
- One or more Figma frame URLs
- `docs/ux_spec.md` and `docs/requirements.md` are optional but improve quality if present (from `/kickoff`)

## Argument Validation
1) Parse `$ARGUMENTS` for platform flag and URLs:
   - `--mobile` or `--platform mobile` → mobile mode
   - `--desktop` or `--platform desktop` → desktop mode
   - No flag → web mode (default)
   - Everything else → Figma URLs

2) If no URLs found: ask the user for Figma frame URLs.

## Algorithm

### Phase 1 — Fetch Figma Data
1) Run the fetch script:
   ```bash
   python3 scripts/figma_fetch.py [--mobile|--desktop] <url1> <url2> ...
   ```
   If the script exits with non-zero (FIGMA_TOKEN not set, invalid URL, API error):
   **STOP** and report the error message to the user.
   This outputs `figma-export/design_data.json` with:
   - `platform`: web/mobile/desktop
   - `platform_config`: output paths for this platform
   - `frames`: node trees with all design properties
   - `summary`: deduplicated colors, text styles, spacings, radii, shadows

2) Read `figma-export/design_data.json`.
3) Read existing project context (if available) — parallel Read:
   - `docs/ux_spec.md`, `docs/requirements.md`, `docs/architecture.md` (from `/kickoff`)
   - `docs/design_philosophy.md` (if exists from a previous run — reuse rather than regenerate)

### Phase 2 — Design Philosophy (descriptive, NOT creative)
4) **If `docs/design_philosophy.md` already exists**: read it, confirm it aligns with the Figma design, and skip to Phase 3. If it contradicts the Figma design, warn the user and ask whether to update.

5) **If it doesn't exist**: analyze the Figma design data and **reverse-engineer** the design philosophy:
   - Study the color palette: warm/cool, saturated/muted, high-contrast/low-contrast
   - Study the typography: serif/sans, weight range, scale ratio
   - Study the spacing: dense/airy, grid pattern
   - Study the border radii and shadows: sharp/rounded, flat/elevated
   - Name the aesthetic direction (2-3 words) based on what you observe
   - Write `docs/design_philosophy.md` describing what the design IS, not what it should be

   **CRITICAL**: This is descriptive, not prescriptive. You are documenting the designer's decisions, not making your own. If the Figma design uses Inter font — document Inter, don't suggest a "more distinctive" alternative.

### Phase 3 — Design System
6) Generate the platform-appropriate design system file from extracted Figma values:
   - **Web**: `docs/design_system.md`
   - **Mobile**: `docs/design_system_mobile.md`
   - **Desktop**: `docs/design_system_desktop.md`

   Contents (all derived from `design_data.json`):
   - **Color palette**: Every color from the summary, grouped by usage (bg, text, accent, border, shadow)
   - **Typography**: Every text style with font-family, weight, size, line-height, letter-spacing. Express as CSS custom properties (web) or theme tokens (mobile/desktop).
   - **Spacing scale**: Extracted values sorted, noting the grid pattern
   - **Border radii**: All unique values
   - **Shadows**: All unique definitions
   - **Components**: List component names from Figma layer names (nodes named "Button/*", "Card/*", "Input/*" etc.) with their key CSS properties

   **Platform-specific additions**:
   - Mobile: touch target minimums (48px), safe area notes, haptic feedback tokens
   - Desktop: keyboard shortcut conventions, window chrome considerations, system menu patterns

### Phase 4 — Wireframes & Interactions
7) Generate wireframes from the Figma frame structure:
   - **Web**: `docs/wireframes.md`
   - **Mobile**: `docs/wireframes_mobile.md`
   - **Desktop**: `docs/wireframes_desktop.md`

   For each frame in design_data.json:
   - Describe the layout (grid structure, component placement, content hierarchy)
   - Note responsive breakpoints (if multiple frames at different widths)
   - List components per screen area

8) Generate interactions spec:
   - **Web**: `docs/interactions.md`
   - **Mobile**: `docs/interactions_mobile.md`
   - **Desktop**: `docs/interactions_desktop.md`

   **Figma is static** — it doesn't contain animations, transitions, or state changes.
   Ask the user the following questions (present all at once):

   a) "What loading states should screens show? (skeleton, spinner, or progressive?)"
   b) "What page transition style? (fade, slide, none?)"
   c) "Any drag-and-drop interactions?"
   d) "Any specific animation moments? (page load reveal, form submit, etc.)"
   e) "If any of these are hard to answer, say 'skip' and I'll use sensible defaults."

   If user skips: derive reasonable defaults from the design philosophy and document them.
   Write the interactions spec with all states (default, loading, empty, error) per screen.

### Phase 4.5 — Copy Guide
9) Generate `docs/copy_guide.md`:
   - Extract all text content from Figma (`text_content` fields in TEXT nodes)
   - Group by screen and component
   - Ask the user: "What tone should the UI copy have? (formal, casual, playful, technical?)"
   - If skipped: infer from the text already in the Figma design
   - Include: labels, placeholders, error message patterns, empty state messages, CTA text

### Phase 5 — Prototype Generation
10) Read `platform_config` from design_data.json to determine output paths.
11) Ensure prototype directory and screens subdirectory exist.
12) Generate or update styles file (CSS for web, theme file for mobile/desktop):
    - All tokens from the design system as CSS custom properties (web) or theme exports (mobile)
    - Component styles using token references
    - Responsive breakpoints from frame widths

13) For each frame, ask the figma-converter agent to generate a screen file:
    - Pass: frame tree, token mapping, platform config
    - Web: `prototype/screens/<name>.html` — semantic HTML, Google Fonts, `file://` compatible
    - Mobile: `prototype-mobile/src/screens/<name>.tsx` — React Native components
    - Desktop: `prototype-desktop/src/screens/<name>.html` — Electron/Tauri compatible HTML

14) Generate index/navigation file:
    - Web: `prototype/index.html`
    - Mobile: `prototype-mobile/App.tsx`
    - Desktop: `prototype-desktop/index.html`

### Phase 6 — Verification
15) **Artifact check**: Grep prototype files for Figma artifacts (position: absolute on layout elements, hardcoded hex that should be tokens). Fix any findings.
16) **Value accounting**: Cross-check summary values against output. No value should silently disappear.
17) **Content check**: Verify Figma text content appears in the output.
18) **Doc completeness**: Verify all expected docs exist for the platform.

19) Present deliverables to the user:
    - List all generated files
    - Token mapping stats
    - Suggest: `open prototype/index.html` (or platform equivalent) to view
    - Suggest: "Run `/implement` — the developer will match these prototypes."

## Error Handling
- `FIGMA_TOKEN` not set: stop, provide setup instructions.
- Invalid URL format: stop, show correct format.
- Figma API 403/404: report with troubleshooting steps.
- No text content in Figma (all images/vectors): warn, generate prototype without copy guide.
- User skips all Phase 4 questions: use sensible defaults, document assumptions.

## Rollback
- All outputs are additive. Re-running overwrites safely.
- Prototype and docs can be safely deleted.

## Guidelines
- **Figma is truth.** Never contradict, override, or "improve" the Figma design. Document it faithfully.
- When the Figma design uses a generic font (Inter, Roboto), document it as-is. Don't suggest alternatives — the designer chose it intentionally.
- When in doubt about a value mapping, keep the Figma value and comment it.
- The output must produce the same docs that `/uiux` would, so downstream skills work identically.