mcp-figma-desktop

What this skill does

# Figma Desktop Skill

Interact with Figma designs directly through the Figma desktop app. Extract UI code (React, Vue, SwiftUI, etc.), design tokens (colors, spacing, typography), screenshots, and metadata from design files. Perfect for implementing design specs, creating component libraries, and maintaining design-code consistency.

## Prerequisites

- Figma desktop app installed and running
- mcp2rest running on http://localhost:28888
- figma-desktop server loaded in mcp2rest (http://127.0.0.1:3845/mcp)
- Node.js 18+ installed

**Verify connection:**
```bash
curl http://localhost:28888/health
curl http://localhost:28888/servers | grep figma-desktop
```

## Quick Start

Most tools work with either:
- **Currently selected node** in Figma (no parameters)
- **Specific node ID** (via `--nodeId` parameter)
- **Figma URL** (automatically extracts node ID)

**Example: Get code for selected component**
```bash
cd .claude/skills/mcp-figma-desktop/scripts

# 1. Select a component in Figma desktop app
# 2. Run this to get React code:
node get_design_context.js --clientFrameworks react

# Output: React component code with props, styling, and structure
```

**Example: Get code from Figma URL**
```bash
# Extract node 123-456 from URL: https://figma.com/design/abc/MyFile?node-id=123-456
node get_design_context.js --nodeId "123:456" --clientFrameworks react,typescript
```

## Available Tools

### Design Code Generation

**get_design_context.js** - Generate production-ready UI code
- **Use for:** Converting designs to React/Vue/SwiftUI/etc components
- **Parameters:**
  - `--nodeId` (optional) - Node ID like "123:456", or omit to use selected node
  - `--clientLanguages` (optional) - Language preferences (e.g., typescript, swift)
  - `--clientFrameworks` (optional) - Framework preferences (e.g., react, vue, swiftui)
  - `--forceCode` (optional) - Force code generation even if not recommended

**get_figjam.js** - Generate code from FigJam boards
- **Use for:** Extracting content from FigJam files (NOT regular Figma files)
- **Parameters:**
  - `--nodeId` (optional) - FigJam node ID or omit for selected node
  - `--clientLanguages` (optional) - Language preferences
  - `--clientFrameworks` (optional) - Framework preferences
  - `--includeImagesOfNodes` (optional) - Include embedded images

**Important:** FigJam URLs use `/board/` instead of `/design/`:
- FigJam: `https://figma.com/board/:fileKey/:fileName?node-id=1-2` → nodeId: "1:2"
- Figma: `https://figma.com/design/:fileKey/:fileName?node-id=1-2` → nodeId: "1:2"

### Design Tokens & Variables

**get_variable_defs.js** - Extract design system variables
- **Use for:** Getting reusable design tokens (colors, spacing, typography)
- **Parameters:**
  - `--nodeId` (optional) - Node ID or omit for selected node
  - `--clientLanguages` (optional) - Output format preferences
  - `--clientFrameworks` (optional) - Framework-specific token formats

**Output example:**
```json
{
  "icon/default/secondary": "#949494",
  "spacing/base": "8px",
  "font/heading/large": "32px"
}
```

### Visual Assets

**get_screenshot.js** - Generate high-quality screenshots
- **Use for:** Creating visual documentation, design reviews, presentations
- **Parameters:**
  - `--nodeId` (optional) - Node to screenshot, or omit for selected
  - `--clientLanguages` (optional) - Format preferences
  - `--clientFrameworks` (optional) - Context for screenshot generation

### Structure & Metadata

**get_metadata.js** - Extract structural information
- **Use for:** Understanding design hierarchy before detailed extraction
- **Returns:** XML with node IDs, types, names, positions, sizes
- **Note:** Prefer `get_design_context` for most use cases
- **Parameters:**
  - `--nodeId` (optional) - Node or page ID (e.g., "0:1" for whole page)
  - `--clientLanguages` (optional)
  - `--clientFrameworks` (optional)

**When to use metadata:**
1. Get overview of large page structure
2. Find specific node IDs for detailed extraction
3. Understand design organization before processing

### Design System

**create_design_system_rules.js** - Generate design system documentation
- **Use for:** Creating design system rules for your codebase
- **Returns:** Prompt/template for documenting design patterns
- **Parameters:**
  - `--clientLanguages` (optional) - Language context
  - `--clientFrameworks` (optional) - Framework context

## Common Workflows

### Workflow 1: Implement Component from Design

**Scenario:** Designer shares Figma link, you need to build the component

**Checklist:**
- [ ] Copy Figma URL from designer (e.g., `https://figma.com/design/abc/Button?node-id=12-34`)
- [ ] Extract node ID from URL: `12-34` becomes `12:34`
- [ ] Get component code: `node get_design_context.js --nodeId "12:34" --clientFrameworks react,typescript`
- [ ] Review generated code and component props
- [ ] Extract design tokens: `node get_variable_defs.js --nodeId "12:34"`
- [ ] Create screenshot for documentation: `node get_screenshot.js --nodeId "12:34"`
- [ ] Implement component using generated code as reference
- [ ] Verify design tokens match

**Example:**
```bash
cd .claude/skills/mcp-figma-desktop/scripts

# 1. Get React + TypeScript code
node get_design_context.js --nodeId "12:34" --clientFrameworks react,typescript

# 2. Get design variables
node get_variable_defs.js --nodeId "12:34"

# 3. Take screenshot for docs
node get_screenshot.js --nodeId "12:34"
```

**Expected output:**
- TypeScript React component with props interface
- Design tokens (colors, spacing, typography)
- High-quality PNG screenshot

### Workflow 2: Build Component Library

**Scenario:** Create reusable component library from design system

**Checklist:**
- [ ] Open design system file in Figma desktop
- [ ] Get page structure: `node get_metadata.js --nodeId "0:1"` (page root)
- [ ] Identify component node IDs from metadata XML
- [ ] For each component:
  - [ ] Extract code: `node get_design_context.js --nodeId "{id}" --clientFrameworks react`
  - [ ] Extract tokens: `node get_variable_defs.js --nodeId "{id}"`
  - [ ] Generate screenshot: `node get_screenshot.js --nodeId "{id}"`
- [ ] Create design system rules: `node create_design_system_rules.js`
- [ ] Organize components into library structure
- [ ] Document usage patterns

**Example: Button component extraction**
```bash
# 1. Get page structure to find button variants
node get_metadata.js --nodeId "0:1" > structure.xml

# From XML, identify button node IDs: 45:12, 45:13, 45:14

# 2. Extract primary button
node get_design_context.js --nodeId "45:12" --clientFrameworks react,typescript > Button.tsx
node get_variable_defs.js --nodeId "45:12" > button-tokens.json
node get_screenshot.js --nodeId "45:12" > button-primary.png

# 3. Repeat for secondary, tertiary variants
```

### Workflow 3: Design-to-Code for FigJam Wireframes

**Scenario:** Convert FigJam wireframes into initial code structure

**Important:** Use `get_figjam.js` for FigJam files, NOT `get_design_context.js`

**Checklist:**
- [ ] Open FigJam board in Figma desktop
- [ ] Select wireframe frame/section
- [ ] Extract structure: `node get_figjam.js --includeImagesOfNodes true`
- [ ] Review generated code skeleton
- [ ] Refine with actual design components

**Example:**
```bash
cd .claude/skills/mcp-figma-desktop/scripts

# From FigJam URL: https://figma.com/board/xyz/Wireframes?node-id=5-10
# Extract node "5:10"

node get_figjam.js --nodeId "5:10" --clientFrameworks react --includeImagesOfNodes true
```

**Expected output:**
- Basic component structure matching wireframe layout
- Placeholder content from FigJam sticky notes/text
- Embedded images if present

### Workflow 4: Extract Design Tokens for Theme

**Scenario:** Create theme configuration from design variables

**Checklist:**
- [ ] Select root design system frame in Figma
- [ ] Extract all variables: `node get_variable_defs.js`
- [ ] Parse output into theme format (CSS custom properties, JS theme object, etc.)
- [ ] Validate variable naming con