# Design-to-Code Workflow with Figma MCP
> **Confidence**: Tier 2 — Based on documented production case studies (Parallel HQ, builder.io), MCP server specifications, and community workflows.
Automated design system implementation using Figma MCP Server enables Product Designers to hand off production-ready specifications to Claude Code, which implements components maintaining 1:1 design-code parity.
---
## Table of Contents
1. [TL;DR](#tldr)
2. [Documented Impact](#documented-impact)
3. [Architecture Overview](#architecture-overview)
4. [3-Tier Token Hierarchy](#3-tier-token-hierarchy)
5. [Prerequisites](#prerequisites)
6. [Core Workflows](#core-workflows)
7. [Code Connect Setup](#code-connect-setup)
8. [Example Prompts](#example-prompts)
9. [Team Adoption Patterns](#team-adoption-patterns)
10. [Anti-Patterns](#anti-patterns)
11. [Implementation Roadmap](#implementation-roadmap)
12. [Resources](#resources)
---
## TL;DR
```
Designer (Figma Make) → Export (Figma Design) → Claude (Figma MCP) → Production Code
Key insight: Design system = source of truth
Claude consumes tokens/components directly from Figma
Implementation maintains design parity automatically
```
---
## Documented Impact
Based on production case studies from January 2026:
| Metric | Improvement | Source |
|--------|-------------|--------|
| Design inconsistencies | 62% reduction | Parallel HQ study |
| Workflow efficiency | 78% improvement | builder.io case study |
| Engineering time saved | 75 days (6 months) | Parallel HQ production data |
| Time-to-market | 56% reduction | Multi-org composite |
| Design technical debt | 82% reduction | Post-implementation audit |
**Typical workflow timing**:
- Single frame → Production component: 2-3 minutes
- Design system drift audit: 3 weeks → 3 minutes
- Token update propagation: Manual hours → Automated seconds
*Sources: builder.io/blog/claude-code-figma-mcp-server, parallelhq.com/blog/automating-design-systems-with-ai, composio.dev/blog/how-to-use-figma-mcp-with-claude-code*
---
## Architecture Overview
### Full Stack
```
[Figma Design File]
↓ (Variables & Styles)
[Tokens Studio Plugin] (optional but recommended)
↓ (JSON export)
[GitHub Repository]
↓ (CI/CD)
[Style Dictionary]
↓ (Transform)
[CSS Custom Properties / Tailwind Config]
↓ (Consumed by)
[Component Library]
↑ (Reads via)
[Claude Code + Figma MCP]
```
### MCP Integration Point
Claude Code accesses Figma through the Figma MCP Server:
```
Claude Code
↓ (uses)
Figma MCP Server (mcp-server-figma)
↓ (authenticates via)
Figma Personal Access Token
↓ (reads)
Figma File (Dev Mode data)
```
**What Claude can access**:
- File structure and frames
- Color/text/effect styles
- Component properties
- Variables (tokens)
- Dev Mode annotations
- Code Connect snippets (if configured)
**What Claude cannot access**:
- Private files without token permissions
- Edit capabilities (read-only)
- Real-time collaboration data
- Version history (only current state)
---
## 3-Tier Token Hierarchy
Modern design systems use a hierarchical token structure. Claude Code understands this hierarchy when consuming Figma data.
| Tier | Definition | Figma Implementation | Code Output |
|------|------------|----------------------|-------------|
| **Base** | Primitive values | Figma Variables (e.g., `blue-600: #0066CC`, `spacing-2: 8px`) | CSS custom properties (`--blue-600`, `--spacing-2`) |
| **Composite** | Combined primitives | Component fills referencing variables | Tailwind config or CSS classes |
| **Semantic** | Contextual meaning | Contextual variable aliases (e.g., `color-interactive-primary` → `blue-600`) | Component props or theme tokens |
### Example Hierarchy
```
Base:
--color-blue-600: #0066CC
--spacing-2: 8px
--radius-md: 4px
Composite:
--button-padding: var(--spacing-2) var(--spacing-4)
--button-border-radius: var(--radius-md)
Semantic:
--interactive-primary: var(--color-blue-600)
--interactive-primary-hover: var(--color-blue-700)
```
**Claude Code behavior**: When given a Figma component, Claude:
1. Extracts referenced variables (base tier)
2. Identifies composite patterns (spacing, sizing)
3. Applies semantic naming from your token conventions
4. Generates code matching this hierarchy
---
## Prerequisites
### For Designers
| Requirement | Details |
|-------------|---------|
| **Figma License** | Dev Mode seat (enables variable inspection, code snippets) |
| **Organized Variables** | Use Figma Variables or Tokens Studio plugin for token management |
| **Component Structure** | Auto Layout, named layers, consistent naming conventions |
| **Frame Naming** | Descriptive frame names (Claude uses these for component names) |
### For Developers
| Requirement | Details |
|-------------|---------|
| **Claude Code** | Version 1.5.0+ (MCP support) |
| **Figma MCP Server** | `npm install -g @modelcontextprotocol/server-figma` |
| **Personal Access Token** | Generated from Figma account settings → Tokens |
| **MCP Configuration** | Token configured in Claude Code settings |
### MCP Configuration
Add to your Claude Code MCP settings (`.claude/mcp.json` or settings UI):
```json
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-figma"],
"env": {
"FIGMA_PERSONAL_ACCESS_TOKEN": "your-token-here"
}
}
}
}
```
**Security note**: Use environment variables for production:
```json
{
"env": {
"FIGMA_PERSONAL_ACCESS_TOKEN": "${FIGMA_TOKEN}"
}
}
```
Then export in your shell: `export FIGMA_TOKEN="figd_..."`
---
## Core Workflows
### Workflow A: Single Frame → Production Component
**Timing**: 2-3 minutes per component
**Steps**:
1. **Designer**: Create component in Figma with proper variables/styles
2. **Designer**: Share Figma file URL with dev/Claude
3. **Developer**: Prompt Claude Code:
```
Read the "Button/Primary" component from Figma file:
https://www.figma.com/design/FILE_KEY
Implement as a React component with TypeScript.
Use Tailwind for styling, mapping Figma variables to our design tokens.
Ensure responsive behavior matches Figma's Auto Layout constraints.
```
4. **Claude**:
- Fetches component via Figma MCP
- Extracts styles, dimensions, spacing
- Maps variables to code tokens
- Generates component with props matching Figma variants
5. **Verification**: `npm run dev` → Visual comparison against Figma
**Example output**:
```tsx
// components/Button/Primary.tsx
interface ButtonProps {
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
children: React.ReactNode;
}
export function PrimaryButton({ size = 'md', disabled, children }: ButtonProps) {
return (
);
}
```
---
### Workflow B: Design System Drift Audit
**Timing**: 3 weeks manual review → 3 minutes automated
**Problem**: Over time, code diverges from design system (magic numbers, hardcoded colors, inconsistent spacing).
**Solution**: Claude audits codebase against Figma source of truth.
**Prompt**:
```
Audit src/components for design system compliance.
Compare against our Figma design system:
https://www.figma.com/design/FILE_KEY
Report:
1. Hardcoded colors not using design tokens
2. Magic number spacing values
3. Components not matching Figma structure
4. Missing responsive patterns
Then propose fixes with token replacements.
```
**Claude output**:
```markdown
## Design System Audit Results
### Issues Found (23 total)
#### Hardcoded Colors (8 instances)
- `src/components/Card.tsx:45` → `#0066CC` should be `var(--interactive-primary)`
- `src/components/Header.tsx:12` → `#F3F4F6` should be `var(--surface-secondary)`
...
#### Magic Numbers (11 instances)
- `src/components/Modal.tsx:23` → `padding: 16px 24px` should be `var(--spacing-4) var(--spacing-6)`
...
#### Structural Mismatches (4 instances)
- `src/components/Button.tsx` → Missing `icon-left` variant present in Figma
...
```
---
### Workflow C: Token Automation Pipeline
**Goal**: Figma variable changes automatically propagate to code.
**Architecture**:
```
Figma Variables
↓ (Tokens Studio export or Figma API)
GitHub Repository (tokens.json)
↓ (GitHub Actions CI/CD)
Style Dictionary Transform
↓ (generates)
CSS / Tailwind / Platform-specific tokens
↓ (commit & deploy)
Production
```
**Setup** (one-time):
1. **Tokens Studio Plugin**: Connect to GitHub repo
2. **Style Dictionary Config**: Define transform rules
3. **GitHub Actions**: Auto-run on token updates
4. **Claude Role**: Review and validate generated tokens
**Developer Prompt** (after CI runs):
```
Review the token update from commit abc1234.
Check if any components need updates to consume new tokens.
Generate migration guide if breaking changes exist.
```
**Claude output**:
```markdown
## Token Update Review (v2.3.0 → v2.4.0)
### Changes
- Added: `--spacing-7`, `--spacing-8` (requested by design)
- Changed: `--interactive-secondary` hue shift 5° (brand refresh)
- Deprecated: `--legacy-blue` (remove by Q3)
### Impact Analysis
- 12 components reference `--interactive-secondary` → Auto-updated via token reference
- 3 components use deprecated `--legacy-blue` → Migration needed
### Migration Required
1. `src/components/LegacyButton.tsx:34` → Replace `--legacy-blue` with `--interactive-primary`
2. `src/components/OldCard.tsx:67` → Replace with new token
3. `src/utils/theme.ts:12` → Update theme export
### Migration Script
[Claude generates codemod or find/replace script]
```
---
### Workflow D: Visual Iteration Loop (Figma + Playwright)
**Goal**: Automated visual regression testing against Figma designs.
**MCP Stack**: Figma MCP + Playwright MCP
**Setup**:
```
Claude Code accesses:
- Figma (design source of truth)
- Playwright (automated browser testing)
```
**Prompt**:
```
Take a screenshot of our Button component in all variants.
Compare against Figma frames from:
https://www.figma.com/design/FILE_KEY → "Button Tests" page
Report any visual differences (color, spacing, typography).
```
**Workflow**:
1. Claude reads Figma frames (expected state)
2. Claude uses Playwright to screenshot live components (actual state)
3. Claude compares (pixel diff or visual inspection)
4. Reports discrepancies with fix suggestions
**Example output**:
```markdown
## Visual Regression Report
### ✅ Matching (5/7)
- Button/Primary/Default
- Button/Primary/Hover
- Button/Secondary/Default
...
### ❌ Mismatches (2/7)
#### Button/Primary/Disabled
- **Issue**: Text opacity 0.4 in code, 0.5 in Figma
- **Fix**: Update `disabled:opacity-50` → `disabled:opacity-40`
- **File**: `src/components/Button.tsx:23`
#### Button/Large
- **Issue**: Padding 12px in code, 16px in Figma
- **Fix**: Update `py-3` → `py-4` (16px)
- **File**: `src/components/Button.tsx:18`
```
---
## Code Connect Setup
**Code Connect** is Figma's no-code tool for linking design components to code snippets. This enhances Claude's ability to generate correct code.
### What It Does
- Designers annotate Figma components with code examples
- Claude reads these annotations via MCP
- Generated code matches team conventions automatically
### Setup (for Designers)
1. In Figma Dev Mode → Select component → Code Connect panel
2. Add code snippet showing how component is used:
```tsx
// Example Code Connect annotation in Figma
```
3. Claude sees this when asked to implement, uses team's exact patterns
### Benefits
| Without Code Connect | With Code Connect |
|---------------------|-------------------|
| Claude generates generic code | Claude uses team conventions |
| Prop naming inconsistent | Props match Figma variants exactly |
| Requires manual correction | Production-ready first pass |
**Reference**: Read more at parallelhq.com/blog (Code Connect UI article)
---
## Alternative: Pencil (IDE-Native Canvas)
**Overview**: [Pencil](https://pencil.dev) brings infinite design canvas directly into Claude Code/Cursor/VSCode, eliminating external tool switching and enabling design-as-code workflows.
### Architecture
**Core Innovation**: Unlike Figma (cloud-based) or Excalidraw (standalone), Pencil embeds the design canvas directly in your IDE where Claude and your code live.
```
Traditional Workflow:
Figma (design) → Export → Claude Code → Implementation → Manual sync
Pencil Workflow:
IDE Canvas (design + AI agents + code) → Git commit → Continuous alignment
```
**Key Features**:
- **WebGL Canvas**: Infinite, performant, fully editable
- **AI Multiplayer Agents**: Parallel agents process design collaboratively
- **Git-Native**: `.pen` files (JSON format) version-controlled alongside code
- **MCP Bi-Directional**: Full read+write access (not just read like Figma MCP)
- **Figma Import**: Copy-paste directly from Figma preserving vectors and styles
### Pencil vs. Figma MCP
| Aspect | Pencil | Figma MCP |
|--------|--------|-----------|
| **Location** | IDE-native (Cursor/VSCode/Claude Code) | External cloud |
| **Format** | `.pen` JSON (open) | Proprietary binary |
| **Versioning** | Git-native (branch/merge/history) | Figma cloud versions |
| **AI Agents** | Multiplayer parallel | Single-threaded via MCP |
| **Collaboration** | Code-first (developers + designers) | Design-first (designers + devs) |
| **MCP Access** | Bi-directional (read+write) | Read-only |
| **Workflow** | Design → Commit → Code in same env | Design → Export → Handoff → Code |
| **Best For** | Engineer-designers, code-centric teams | Traditional design-dev separation |
| **Maturity** | Emerging (launched Jan 2026) | Mature (2024+) |
| **Pricing** | Currently free, TBD future | Freemium (free tier available) |
### When to Use Pencil
✅ **Good Fit**:
- Team uses Cursor or VSCode + Claude Code as primary environment
- Engineer-designers comfortable with terminal/IDE workflows
- Projects requiring tight design-code alignment (design-as-code paradigm)
- Desire for git-native design versioning (branch protection, rollback, etc.)
- Want to leverage parallel AI agents for design automation
⚠️ **Consider Carefully**:
- Traditional design team (non-technical) → Figma may be better
- Need enterprise SLA/support → Pencil still maturing
- Complex design system with 50+ components → Figma ecosystem more mature
- Team not using Cursor/VSCode → Limited compatibility
### Setup
1. **Install Pencil extension**:
- Visit [pencil.dev](https://pencil.dev)
- Follow installation for Cursor/VSCode/Claude Code
- Create account (currently free)
2. **Create first canvas**:
```bash
# Open IDE, launch Pencil extension
# Create new .pen file in your repo
# Design on infinite canvas
```
3. **Git workflow**:
```bash
git add design/homepage.pen
git commit -m "feat(design): add homepage hero section"
git push
```
4. **Claude integration**:
- Claude can read .pen files via MCP
- Prompt: "Implement the Button component from design/components.pen"
- Claude extracts design specs and generates code
### Example Prompt
```
Read the "Hero Section" from design/homepage.pen.
Implement as React component with:
- Responsive behavior matching canvas breakpoints
- Animations from design (fade-in, slide-up)
- Copy exactly as specified in canvas
- Use Tailwind for styling
Ensure pixel-perfect match with design specs.
```
### Founder & Backing
**Tom Krcha** (CEO, Pencil):
- Co-founder Adobe XD (2014-2018), 10 years at Adobe
- Prior exits: Alter Avatars (acquired by Google), Around (acquired by Miro)
- 14+ years development experience
**Funding**: a16z Speedrun (~$1M) + KAYA VC
**Traction**: 1M+ views on launch, thousands of signups including Microsoft, Shopify, Uber executives.
### Maturity Note
**⚠️ Status**: Launched January 2026 (very recent). Strong early signals but documentation and ecosystem still maturing.
**Recommendations**:
- **Production projects**: Pilot with 1-2 non-critical features first
- **New projects**: Safe to adopt for teams on Cursor/Claude Code
- **Traditional workflows**: Stick with Figma MCP until Pencil matures (3-6 months)
**Monitor**: Pricing announcement, public GitHub repo, mature documentation expected Q2 2026.
---
## Example Prompts
### Component Implementation
```
Implement the "Card/Product" component from our Figma design system:
[Figma URL]
Requirements:
- Use our existing design tokens from tailwind.config.ts
- Include hover states matching Figma interactions
- Implement all variants (default, featured, compact)
- Add TypeScript types for all props
```
### Design System Expansion
```
Our design team added a new "Badge" component to Figma:
[Figma URL → Badge frame]
Generate:
1. React component with all variants
2. Storybook stories
3. Unit tests for prop combinations
4. Update design system docs
```
### Token Validation
```
Compare the color tokens in our Tailwind config against
Figma variables from: [Figma URL]
Report any mismatches and generate update script.
```
### Responsive Implementation
```
Implement the "Hero" section from Figma with exact responsive behavior:
[Figma URL → Hero/Responsive frame]
Figma has 3 breakpoints configured. Match these precisely.
```
### Accessibility Audit
```
Review the "Modal" component implementation against Figma specs:
[Figma URL]
Check:
- Focus management matches Figma's interaction flow
- Color contrast meets WCAG AA (Figma has contrast checker)
- Keyboard navigation (Figma annotations specify tab order)
```
### Design QA Before Handoff
```
Review the "Checkout Flow" frames for implementation readiness:
[Figma URL → Checkout Flow page]
Check:
- All interactive states defined (hover, focus, disabled, error)
- Variables used consistently (no magic values)
- Auto Layout constraints are implementable
- Missing anything needed for production code?
```
### Multi-Component Atomic Implementation
```
Implement the atomic design system components in order:
1. Atoms: [Figma URL → Atoms page]
- Button, Input, Label, Badge
2. Molecules: [Figma URL → Molecules page]
- FormField (Label + Input + Error)
- SearchBar (Input + Button)
3. Organisms: [Figma URL → Organisms page]
- LoginForm (using molecules)
Ensure each level only imports from lower levels.
```
---
## Team Adoption Patterns
### For Product Designers
**New workflow**:
1. Design in Figma with proper variable structure
2. Use Figma Make for rapid prototyping
3. Export to Figma Design with Dev Mode enabled
4. Share file URL + specific frames with dev team
5. Claude consumes design → Generates implementation
6. Designer reviews code output visually (not reading code)
**Key insight**: Designers don't need to learn code. They review implementation by visual comparison against Figma.
### For Developers
**New workflow**:
1. Receive Figma URL from designer
2. Prompt Claude to implement from Figma source
3. Review generated code for architecture fit
4. Run visual comparison (Playwright or manual)
5. Commit production-ready component
**Time saved**: Skip manual pixel-perfect implementation. Focus on logic, not layout matching.
### For Product Managers
**New capability**: Request design implementation estimates based on Figma frames.
**Prompt for PMs**:
```
Review the "Dashboard Redesign" Figma file:
[Figma URL]
Estimate implementation complexity:
- How many new components needed?
- Which existing components can be reused?
- Any technical blockers?
Provide rough timeline for dev implementation.
```
Claude output:
```markdown
## Implementation Analysis
### Scope
- 12 frames total
- 4 new components (DataTable, MetricCard, FilterPanel, DateRangePicker)
- 8 existing components reused
### Complexity Assessment
- **Low**: MetricCard (similar to existing Card, 1-2h)
- **Medium**: FilterPanel (multi-select logic, 4-6h)
- **High**: DataTable (sorting, pagination, virtualization, 2-3 days)
- **High**: DateRangePicker (third-party library integration, 1-2 days)
### Technical Considerations
- DataTable needs backend API for server-side pagination
- DateRangePicker: evaluate date-fns vs dayjs vs native
- FilterPanel state management (local vs global)
### Estimated Timeline
- Development: 5-7 days
- Code review + QA: 2 days
- Total: 1.5-2 weeks
```
---
## Anti-Patterns
| ❌ Anti-Pattern | Why It Fails | ✅ Correct Approach |
|----------------|-------------|-------------------|
| **Manual design transcription** | Error-prone, time-consuming, drift inevitable | Let Claude read Figma directly via MCP |
| **Screenshots as specs** | No token data, no interactivity, ambiguous | Share Figma URLs, let Claude access structured data |
| **Hardcoded values** | Breaks when design system updates | Use design tokens from Figma variables |
| **Designer codes** | Inefficient use of designer skills | Designer designs → Claude codes → Dev reviews |
| **Developer guesses spacing** | Inconsistent with design system | Claude extracts exact values from Figma |
| **No Code Connect annotations** | Generic code output | Annotate once → Claude uses team conventions |
| **Skipping visual comparison** | Implementation drift | Always verify against Figma source |
| **Token naming mismatch** | Figma variables ≠ code tokens | Establish naming convention, use Style Dictionary |
| **Missing responsive specs** | Developer guesses breakpoints | Figma has responsive frames → Claude reads exact specs |
| **Single-tier tokens** | Inflexible, hard to theme | Use 3-tier hierarchy (base/composite/semantic) |
---
## Implementation Roadmap
### Phase 1: Foundation (Week 1-2)
**Goal**: Basic Figma → Claude → Code pipeline
- [ ] Install Figma MCP Server
- [ ] Configure personal access token
- [ ] Test connection: Claude reads public Figma file
- [ ] Create project CLAUDE.md with design system conventions
- [ ] Implement 3-5 simple components (Button, Input, Badge)
- [ ] Establish visual QA process (manual comparison)
**Success criteria**:
- Claude generates component from Figma URL
- Output matches design visually
- Dev team understands workflow
---
### Phase 2: Scaling (Week 3-4)
**Goal**: Full design system implementation + automation
- [ ] Implement 20+ components from Figma library
- [ ] Set up token automation (Tokens Studio + Style Dictionary)
- [ ] Create component testing suite (Storybook + visual regression)
- [ ] Train designers on variable hygiene
- [ ] Document team conventions in CLAUDE.md
- [ ] Run first design system drift audit
**Success criteria**:
- 80%+ of UI components auto-generated
- Token updates propagate automatically
- Designers confident in handoff process
---
### Phase 3: Orchestration (Week 5+)
**Goal**: Multi-MCP workflows + continuous sync
- [ ] Integrate Playwright MCP for automated visual testing
- [ ] Set up CI/CD for design-code parity checks
- [ ] Create Figma → GitHub → Production pipeline
- [ ] Implement design system governance (linting, audits)
- [ ] Enable non-devs to trigger Claude implementations (tickets, Slack)
- [ ] Measure metrics (TTM, inconsistency rate, dev time saved)
**Success criteria**:
- Design updates → Production in <1 day
- Zero manual design transcription
- Measurable team velocity increase
---
## Resources
### Official Documentation
- **Figma MCP Server**: [@modelcontextprotocol/server-figma](https://github.com/modelcontextprotocol/servers/tree/main/src/figma) (GitHub)
- **Figma Developer Docs**: [figma.com/developers](https://www.figma.com/developers)
- **Style Dictionary**: [amzn.github.io/style-dictionary](https://amzn.github.io/style-dictionary/)
- **Tokens Studio Plugin**: [tokens.studio](https://tokens.studio/)
### Case Studies & Tutorials
- **builder.io**: "Claude Code + Figma MCP Server: AI Design-to-Code Workflow" (January 2026)
- [builder.io/blog/claude-code-figma-mcp-server](https://www.builder.io/blog/claude-code-figma-mcp-server)
- Production metrics, workflow examples
- **Vladimir Siedykh**: "Multi-MCP Orchestration with Claude Code"
- [vladimirsiedykh.com/blog/claude-code-mcp-workflow](https://vladimirsiedykh.com/)
- Figma + Playwright + Linear integration
- **Parallel HQ**: "Automating Design Systems with AI"
- [parallelhq.com/blog/automating-design-systems-with-ai](https://parallelhq.com/)
- 75 days saved, Code Connect UI guide
- **Composio**: "How to Use Figma MCP with Claude Code"
- [composio.dev/blog/how-to-use-figma-mcp-with-claude-code](https://composio.dev/)
- Token hierarchy patterns, setup guide
### Community Resources
- **Figma Community**: Search "Design System Tokens" for starter templates
- **MCP Registry**: [mcp.run](https://mcp.run/) → Figma server examples
- **Discord**: Anthropic Discord → #mcp-servers channel
### Related Workflows
- [Working with Images](../ultimate-guide.md#24-working-with-images) — Claude Code image analysis
- [ASCII Art & Wireframing](../ultimate-guide.md#wireframing-tools) — Low-fidelity design iteration
- [Playwright MCP](../ultimate-guide.md#playwright-mcp) — Visual regression testing
---
## See Also
- [../ultimate-guide.md#figma-mcp](../ultimate-guide.md) — Main guide Figma MCP section
- [examples/claude-md/product-designer.md](../../examples/claude-md/product-designer.md) — Product Designer CLAUDE.md template
- [../cheatsheet.md](../cheatsheet.md) — Quick reference