prototype-to-figma-skill

# Prototype → Figma Skill > Skill by [ara.so](https://ara.so) — Design Skills collection. Converts working Claude Code prototypes into structured Figma design files by exploding interaction flows into state-by-state frames, mapping components to your Figma design system, and annotating triggers, transitions, and edge cases natively in Figma. ## What This Skill Does When a user builds a prototype in Claude Code, this skill: 1. **Analyzes the prototype source** — inventories components, maps interaction flows, identifies all UI states 2. **Maps to design system** — searches linked Figma libraries for matching DS components; flags unmatched elements with "No DS match" badges 3. **Creates one frame per interaction state** — every meaningful step in a user flow becomes a separate Figma frame 4. **Annotates interactions** — adds native Figma Dev Mode annotations with filterable categories (Interaction, Navigation, Validation, Error Handling, etc.) 5. **Adds flow arrows** — visual connectors showing user path through states 6. **Creates overview frame** — table of contents with legend and open questions for reviewers 7. **Optionally links Code Connect** — maps Figma components back to codebase ## Key Capabilities - **Design system aware** — uses real components from target file's linked libraries - **Primitive fallback** — builds missing components from Figma primitives (never skips elements) - **Multi-tier output** — builds directly in Figma on supported clients, generates spec documents on others - **Code Connect integration** — creates bidirectional links between Figma and code - **Automatic file creation** — creates new Figma file if no URL provided ## When to Use This Skill User says things like: - "Take this prototype and put it in Figma so the team can review it" - "Explode this into Figma frames for async feedback" - "Create Figma specs from my prototype for design review" - "Make this prototype reviewable by the design team" ## Required MCP Tools This skill requires the Figma MCP server with these tools available: - `use_figma` — select target file - `search_design_system` — find matching components - `get_design_context` — understand file structure - `get_metadata` — read component details - `get_screenshot` — verify output - `get_code_connect_map` — read existing mappings - `get_context_for_code_connect` — understand component context - `get_code_connect_suggestions` — get AI suggestions for mappings - `send_code_connect_mappings` — batch create mappings - `add_code_connect_map` — create individual mapping - `whoami` — get user info for file creation - `create_new_file` — create new Figma file ## Installation Check Before using this skill, verify Figma MCP is installed: ```bash # Check Claude Desktop config cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | grep figma # Or for Claude Code cat ~/.claude/mcp_config.json | grep figma ``` Expected output should include `@figma/mcp-server` or similar. ## Workflow Steps ### 1. Resolve Target File If user provides Figma URL: ```typescript await use_figma({ url: "https://figma.com/design/abc123/MyFile" }); ``` If no URL provided, create new file: ```typescript // Get user info const user = await whoami(); // Create new file const newFile = await create_new_file({ name: `${prototypeName} — Prototype Review`, team_id: user.team_id // or user.default_team_id }); await use_figma({ url: newFile.url }); ``` ### 2. Analyze Prototype Source Read the prototype files and extract: - Component inventory (Button, Input, Modal, etc.) - Interaction flows (user actions → state changes) - UI states (initial, loading, success, error, etc.) - Data flows (form submissions, API calls, etc.) Example analysis structure: ```typescript interface PrototypeAnalysis { components: { name: string; // e.g. "PrimaryButton" type: string; // e.g. "Button" props: string[]; // e.g. ["label", "onClick", "disabled"] variants: string[]; // e.g. ["default", "hover", "disabled"] }[]; flows: { name: string; // e.g. "Login Flow" states: { id: string; // e.g. "login-initial" label: string; // e.g. "Login Form (Empty)" components: string[]; interactions: { trigger: string; // e.g. "Click 'Sign In'" action: string; // e.g. "Validate and submit" nextState: string; // e.g. "login-loading" condition?: string; // e.g. "If fields valid" }[]; }[]; }[]; } ``` ### 3. Map to Design System For each component in the prototype: ```typescript // Search for matching DS component const results = await search_design_system({ query: componentName, component_type: componentType, // "Button", "Input", etc. limit: 5 }); // If match found, get metadata if (results.length > 0) { const metadata = await get_metadata({ node_id: results[0].node_id }); // Store mapping componentMap.set(componentName, { figma_node_id: results[0].node_id, figma_name: results[0].name, variants: metadata.variants, props: metadata.properties }); } else { // Mark for primitive fallback componentMap.set(componentName, { needs_primitive_fallback: true, primitive_type: componentType }); } ``` ### 4. Plan Page Structure Organize frames by flow: ``` Page: "Login Flow" ├─ Overview Frame (legend + TOC) ├─ State 1: Login Form (Empty) ├─ State 2: Login Form (Validation Error) ├─ State 3: Login Form (Loading) ├─ State 4: Login Success └─ State 5: Login Error (Network) ``` Calculate frame positions: ```typescript const FRAME_WIDTH = 1440; // desktop, or 390 for mobile const FRAME_HEIGHT = 900; // desktop, or 844 for mobile const HORIZONTAL_SPACING = 200; const VERTICAL_SPACING = 200; function calculateFramePosition(index: number, perRow: number = 3) { const row = Math.floor(index / perRow); const col = index % perRow; return { x: col * (FRAME_WIDTH + HORIZONTAL_SPACING), y: row * (FRAME_HEIGHT + VERTICAL_SPACING) }; } ``` ### 5. Build Frames in Figma **CRITICAL**: Never call `createComponent()` — always use `createInstance()` for DS components or primitives for fallbacks. For matched DS components: ```typescript // Create instance of DS component const buttonInstance = await figma.createInstance({ component_id: componentMap.get("PrimaryButton").figma_node_id, parent_id: frameId, x: 100, y: 200, properties: { variant: "default", label: "Sign In" } }); ``` For components needing primitive fallback: ```typescript // Build from primitives (example: Button) const buttonGroup = await figma.createFrame({ name: "Button (No DS match)", parent_id: frameId, x: 100, y: 200, width: 120, height: 40, fills: [{ type: "SOLID", color: { r: 0.2, g: 0.4, b: 1 } }], cornerRadius: 8 }); const buttonLabel = await figma.createText({ parent_id: buttonGroup.id, characters: "Sign In", fontSize: 16, fills: [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }] }); // Add "No DS match" badge const badge = await figma.createFrame({ name: "⚠️ No DS match", parent_id: buttonGroup.id, x: -10, y: -10, width: 100, height: 20, fills: [{ type: "SOLID", color: { r: 1, g: 0.8, b: 0 } }] }); ``` ### 6. Add Annotations Use native Figma Dev Mode annotations with categories: ```typescript await figma.addAnnotation({ node_id: buttonInstance.id, category: "Interaction", text: "Trigger: Click\nAction: Validate form fields\nNext: → Login Form (Loading) if valid, → Login Form (Error) if invalid" }); await figma.addAnnotation({ node_id: emailInput.id, category: "Validation", text: "Required field\nValidation: Must be valid email format\nError message: 'Please enter a valid email'" }); await figma.addAnnotation({ node_id: errorBanner.id, category: "Error Handling", text: "Shown when: Network request fails\nDuration: Persistent until dismissed\nDismiss: Click X icon or retry" }); ``` Categories to use: - `Interaction` — clicks, hovers, focus - `Navigation` — route changes, deep links - `Validation` — input rules, error states - `Error Handling` — error scenarios, recovery - `Data Flow` — API calls, state updates - `Edge Cases` — empty states, loading, timeouts ### 7. Add Flow Arrows Create connector arrows between frames: ```typescript await figma.createConnector({ start_node_id: state1Frame.id, end_node_id: state2Frame.id, stroke_weight: 2, stroke_color: { r: 0.5, g: 0.5, b: 0.5 }, label: "Click 'Sign In'" }); ``` ### 8. Create Overview Frame First frame in each flow page: ```typescript const overviewFrame = await figma.createFrame({ name: "📋 Overview", width: FRAME_WIDTH, height: FRAME_HEIGHT, fills: [{ type: "SOLID", color: { r: 0.98, g: 0.98, b: 0.98 } }] }); // Add title await figma.createText({ parent_id: overviewFrame.id, characters: "Login Flow — Prototype Review", fontSize: 32, fontWeight: 700, y: 40 }); // Add legend await figma.createText({ parent_id: overviewFrame.id, characters: `Legend: • 🟦 Frame = One UI state • ➡️ Arrow = User action / transition • 📝 Annotation = Interaction detail • ⚠️ Badge = No design system match (built from primitives)`, fontSize: 16, y: 120 }); // Add TOC await figma.createText({ parent_id: overviewFrame.id, characters: `States in this flow: 1. Login Form (Empty) 2. Login Form (Validation Error) 3. Login Form (Loading) 4. Login Success 5. Login Error (Network)`, fontSize: 16, y: 250 }); // Add open questions await figma.createText({ parent_id: overviewFrame.id, characters: `Open questions for reviewers: • Should "Forgot Password" link to modal or new page? • Do we show loading spinner in button or overlay entire form? • How long should success message persist?`, fontSize: 16, y: 450, fills: [{ type: "SOLID", color: { r: 0.8, g: 0.4, b: 0 } }] }); ``` ### 9. Create Code Connect Mappings (Optional) If user wants Code Connect integration: ```typescript // Get existing mappings const existingMaps = await get_code_connect_map({ file_key: fileKey }); // Get suggestions for unmapped components const suggestions = await get_code_connect_suggestions({ component_id: buttonComponentId, code_snippet: `<Button variant="primary" onClick={handleClick}>Sign In</Button>` }); // Create mappings const mappings = componentMap.entries().map(([codeName, figmaInfo]) => ({ figma_node_id: figmaInfo.figma_node_id, code_location: `src/components/${codeName}.tsx`, code_snippet: getComponentSnippet(codeName), framework: "react" // or "vue", "svelte", etc. })); await send_code_connect_mappings({ mappings: mappings }); ``` ### 10. Verify and Present ```typescript // Take screenshot of output const screenshot = await get_screenshot({ node_id: pageId, scale: 0.5 // overview scale }); // Present to user return `✅ Prototype converted to Figma! File: ${figmaFileUrl} Created: • ${flowCount} flows • ${frameCount} state frames • ${annotationCount} interaction annotations • ${componentMatchCount} design system components used • ${primitiveFallbackCount} components built from primitives (flagged with ⚠️) ${codeConnectEnabled ? `Code Connect: ${mappingCount} mappings created` : ''} Open questions for reviewers: ${openQuestions.join('\n')} [Screenshot attached]`; ``` ## Common Patterns ### Pattern: Detecting Prototype Framework ```typescript function detectFramework(prototypeFiles: string[]): string { const hasReact = prototypeFiles.some(f => f.includes('import React') || f.includes('from "react"') ); const hasVue = prototypeFiles.some(f => f.includes('<template>') || f.includes('from "vue"') ); const hasSvelte = prototypeFiles.some(f => f.includes('<script>') && f.endsWith('.svelte') ); if (hasReact) return 'react'; if (hasVue) return 'vue'; if (hasSvelte) return 'svelte'; return 'html'; // vanilla } ``` ### Pattern: Grouping Micro-Interactions Group very small interactions (hover, focus) into a single frame with annotations: ```typescript function shouldGroupInteractions(interactions: Interaction[]): boolean { // If all interactions are micro-interactions (hover, focus, blur) const microTypes = ['hover', 'focus', 'blur', 'mouseover', 'mouseout']; return interactions.every(i => microTypes.includes(i.type)); }