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/*)

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:

   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.