prototype-to-figma-skill

Prototype → Figma Skill

Skill by 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:

Analyzes the prototype source — inventories components, maps interaction flows, identifies all UI states
Maps to design system — searches linked Figma libraries for matching DS components; flags unmatched elements with "No DS match" badges
Creates one frame per interaction state — every meaningful step in a user flow becomes a separate Figma frame
Annotates interactions — adds native Figma Dev Mode annotations with filterable categories (Interaction, Navigation, Validation, Error Handling, etc.)
Adds flow arrows — visual connectors showing user path through states
Creates overview frame — table of contents with legend and open questions for reviewers
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:

# 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:

await use_figma({
  url: "https://figma.com/design/abc123/MyFile"
});

If no URL provided, create new file:

// 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:

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:

// 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:

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:

// 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:

// 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:

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:

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:

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:

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

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

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:

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));
}

// Instead of 5 frames for hover states, create 1 frame with annotations:
await figma.addAnnotation({
  node_id: button.id,
  category: "Interaction",
  text: `Hover: Background darkens to #1a3d8f
Focus: 2px blue outline appears
Click: Ripple animation, navigate to /dashboard`
});

Pattern: Handling Responsive Variants

function explodeResponsiveStates(state: UIState): UIState[] {
  if (!state.hasResponsiveVariants) return [state];
  
  return [
    { ...state, viewport: 'mobile', frameWidth: 390, frameHeight: 844 },
    { ...state, viewport: 'tablet', frameWidth: 768, frameHeight: 1024 },
    { ...state, viewport: 'desktop', frameWidth: 1440, frameHeight: 900 }
  ];
}

Pattern: Primitive Button Fallback

async function createPrimitiveButton(
  parent_id: string,
  x: number,
  y: number,
  label: string,
  variant: 'primary' | 'secondary' = 'primary'
) {
  const colors = {
    primary: { bg: { r: 0.2, g: 0.4, b: 1 }, fg: { r: 1, g: 1, b: 1 } },
    secondary: { bg: { r: 0.95, g: 0.95, b: 0.95 }, fg: { r: 0.2, g: 0.2, b: 0.2 } }
  };
  
  const group = await figma.createFrame({
    name: `Button: ${label} (No DS match)`,
    parent_id,
    x,
    y,
    width: Math.max(120, label.length * 10),
    height: 40,
    fills: [{ type: "SOLID", color: colors[variant].bg }],
    cornerRadius: 8,
    paddingLeft: 16,
    paddingRight: 16
  });
  
  await figma.createText({
    parent_id: group.id,
    characters: label,
    fontSize: 16,
    fontWeight: 500,
    fills: [{ type: "SOLID", color: colors[variant].fg }],
    textAlignHorizontal: "CENTER",
    textAlignVertical: "CENTER"
  });
  
  // Add badge
  await figma.createFrame({
    name: "⚠️ No DS match",
    parent_id: group.id,
    x: -12,
    y: -12,
    width: 110,
    height: 24,
    fills: [{ type: "SOLID", color: { r: 1, g: 0.8, b: 0 } }],
    cornerRadius: 4
  });
  
  return group;
}

Troubleshooting

"No Figma MCP tools available"

Cause: Figma MCP server not installed or not running.

Solution:

# Install Figma MCP
npx @figma/mcp-server init

# Or check Claude Desktop config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

"Cannot create component"

Cause: Skill is calling createComponent() instead of using instances or primitives.

Solution: NEVER call createComponent(). Always:

Use createInstance() for DS components
Build from primitives (createFrame, createText, etc.) for fallbacks

"Design system search returns no results"

Cause: Target file has no linked libraries, or component naming mismatch.

Solution:

Verify linked libraries in Figma file settings
Try fuzzy search: search_design_system({ query: "btn primary" }) instead of exact "PrimaryButton"
Fall back to primitives if no match after 2-3 search attempts

"Too many frames created"

Cause: Exploding every micro-interaction into separate frames.

Solution: Group hover/focus/blur into single frame with annotations (see pattern above).

"Annotations not visible"

Cause: User not in Dev Mode, or annotations have no category.

Solution: Always specify category. Remind user to switch to Dev Mode in Figma.

"Code Connect mappings fail"

Cause: Invalid code snippet format, or component not in file.

Solution:

// Get context first
const context = await get_context_for_code_connect({
  component_id: nodeId
});

// Then create mapping with valid snippet
await add_code_connect_map({
  figma_node_id: nodeId,
  code_location: "src/components/Button.tsx",
  code_snippet: `import { Button } from "./Button";\n\n<Button variant="primary">Click me</Button>`,
  framework: "react"
});

Output Tier Compatibility

This skill produces different outputs based on client capabilities:

Tier 1 (Full build in Figma): Claude Code, Claude Desktop, Cursor, VS Code, Copilot CLI, Augment Code, Factory, Firebender, Codex

Builds frames directly in Figma
Creates Code Connect mappings
Adds native annotations

Tier 2 (Spec document): Android Studio, Gemini CLI, Kiro, Amazon Q, Openhands

Generates markdown spec document
Includes frame-by-frame descriptions
No direct Figma manipulation

Tier 3 (Build only): Replit

Builds frames in Figma
No Code Connect support

Check available tools at runtime:

const hasCodeConnect = tools.includes('get_code_connect_suggestions');
const canBuildInFigma = tools.includes('use_figma');

Environment Variables

This skill does not require API keys — it uses Figma MCP tools which handle authentication via OAuth.

Users must have Figma account connected to their Claude client.

Best Practices

Always verify file access — call use_figma() before any other Figma operations
Never skip elements — if no DS match, build from primitives and flag with badge
Group micro-interactions — don't create 10 frames for hover states
Organize by flow — one page per user flow, not one giant page
Use consistent naming — "State 1: [Description]" format for frame names
Add legend on every page — overview frame explaining notation
Flag open questions — surface design decisions that need input
Take screenshots — verify output before presenting to user
Provide file URL — always share direct link to Figma file in response

Example Full Workflow

// User: "Put this login prototype in Figma"

// 1. Create new file (no URL provided)
const user = await whoami();
const file = await create_new_file({
  name: "Login Prototype — Review",
  team_id: user.team_id
});
await use_figma({ url: file.url });

// 2. Analyze prototype
const analysis = analyzePrototype(prototypeFiles);
// → { flows: [{ name: "Login Flow", states: [...] }], components: [...] }

// 3. Map components
for (const comp of analysis.components) {
  const results = await search_design_system({
    query: comp.name,
    component_type: comp.type
  });
  if (results.length > 0) {
    componentMap.set(comp.name, results[0]);
  } else {
    componentMap.set(comp.name, { primitive: true, type: comp.type });
  }
}

// 4. Create page
const page = await figma.createPage({ name: "Login Flow" });

// 5. Create overview frame
const overview = await createOverviewFrame(page.id, analysis.flows[0]);

// 6. Create state frames
for (let i = 0; i < analysis.flows[0].states.length; i++) {
  const state = analysis.flows[0].states[i];
  const pos = calculateFramePosition(i + 1); // +1 to skip overview
  
  const frame = await figma.createFrame({
    name: `State ${i + 1}: ${state.label}`,
    parent_id: page.id,
    x: pos.x,
    y: pos.y,
    width: 1440,
    height: 900
  });
  
  // Build components
  for (const compName of state.components) {
    const mapping = componentMap.get(compName);
    if (mapping.primitive) {
      await createPrimitiveButton(frame.id, 100, 100, compName);
    } else {
      await figma.createInstance({
        component_id: mapping.figma_node_id,
        parent_id: frame.id
      });
    }
  }
  
  // Add annotations
  for (const interaction of state.interactions) {
    await figma.addAnnotation({
      node_id: frame.id,
      category: "Interaction",
      text: `${interaction.trigger} → ${interaction.action}`
    });
  }
  
  // Add flow arrow to next state
  if (i < analysis.flows[0].states.length - 1) {
    await figma.createConnector({
      start_node_id: frame.id,
      end_node_id: nextFrameId
    });
  }
}

// 7. Screenshot and present
const screenshot = await get_screenshot({ node_id: page.id });
return `✅ Prototype in Figma: ${file.url}`;

This skill is part of the Design Skills collection at ara.so. For issues or contributions, see the GitHub repo.

About this skill

What This Skill Does

Key Capabilities

When to Use This Skill

Required MCP Tools

Installation Check

Workflow Steps

1. Resolve Target File

2. Analyze Prototype Source

3. Map to Design System

4. Plan Page Structure

5. Build Frames in Figma

6. Add Annotations

7. Add Flow Arrows

8. Create Overview Frame

9. Create Code Connect Mappings (Optional)

10. Verify and Present

Common Patterns

Pattern: Detecting Prototype Framework

Pattern: Grouping Micro-Interactions

Pattern: Handling Responsive Variants

Pattern: Primitive Button Fallback

Troubleshooting

"No Figma MCP tools available"

"Cannot create component"

"Design system search returns no results"

"Too many frames created"

"Annotations not visible"

"Code Connect mappings fail"

Output Tier Compatibility

Environment Variables

Best Practices

Example Full Workflow