Figma-to-Code Workflow

## Prerequisites

- Figma account with Dev or Full seat (paid plan) for unlimited tool calls
- AI coding agent with MCP support (VS Code + Copilot, Cursor, Claude Code)
- Figma MCP server connected (`https://mcp.figma.com/mcp`)

## Step 1: Prepare Your Figma File

Good Figma structure = good generated code.

- **Use components** for every reusable element (buttons, inputs, cards)
- **Use variables** for all tokens: colors, spacing, border-radius, typography
- **Name layers semantically**: `HeroSection`, `PricingCard`, not `Frame 47`
- **Apply Auto Layout** to communicate responsive intent
- **Add annotations** for behavior (hover states, transitions, conditional visibility)

## Step 2: Set Up Code Connect (Optional but Recommended)

Code Connect maps Figma components to your actual codebase components. Without it, the AI guesses which component to use.

```bash
# Install Code Connect CLI
npm install -g @figma/code-connect

# Initialize in your project
figma connect init

# Publish component mappings
figma connect publish
```

This creates a mapping file that tells the Figma MCP server: "When you see this Figma component, use `<Button>` from `@/components/ui/button`".

## Step 3: Add Agent Rules

Create a rules file for your IDE to enforce consistent Figma-to-code workflows:

```markdown
---
description: Figma MCP server rules
applyTo: "**/*"
---

## Required flow for every Figma implementation

1. Run `get_design_context` first to fetch the structured representation
2. If response is truncated, run `get_metadata` then re-fetch specific nodes
3. Run `get_screenshot` for visual reference
4. Only after both context and screenshot, download assets and implement
5. Translate output into this project's tokens and conventions
6. Validate against Figma screenshot for 1:1 parity

## Asset rules

- Use localhost sources directly when the MCP server returns them
- Never import new icon packages — all assets come from the Figma payload
- Never create placeholder images if a source URL is provided

## Code rules

- Use project design tokens, not hardcoded values
- Reuse existing components from the design system
- Follow existing routing and state management patterns
- Place generated components in the correct directory
```

## Step 4: Implementation Workflow

### Small component (button, card, input)

```
Prompt: "Implement this Figma component as a React component:
[paste Figma link]
Use our design tokens from @/lib/tokens and place it in src/components/ui/"
```

### Full page

Break the page into sections:

1. Copy the link to the **header section** → generate
2. Copy the link to the **hero section** → generate
3. Copy the link to the **content grid** → generate
4. Compose them in a page component

### Extract tokens only

```
Prompt: "Get the variable definitions from this Figma file:
[paste Figma link]
Output them as CSS custom properties matching our existing token format"
```

## Step 5: Design System Sync

For ongoing projects, set up a periodic sync:

1. **Audit compliance**: Use the `ds-compliance-audit` community skill to check your Figma file for token/component violations
2. **Export tokens**: Extract variables via `get_variable_defs` and compare with your codebase tokens
3. **Update Code Connect**: After adding new components, run `figma connect publish` to keep mappings current

## Common Pitfalls

- **Selecting too much at once**: Large selections time out or produce incomplete results. Select individual components.
- **Not using variables**: If your Figma file uses hardcoded colors, the AI will hardcode colors too.
- **Ignoring Code Connect**: Without it, every `<Button>` in Figma might generate a new custom button component instead of reusing yours.
- **Skipping the screenshot step**: The screenshot provides visual context that the structured data alone may miss (shadows, gradients, exact spacing).