feat(guide): add Product Designer learning path and design-to-code workflow
Add comprehensive resources for Product Designers working with Claude Code via Figma MCP: - New workflow: guide/workflows/design-to-code.md (700 lines) - Documented metrics: 62% reduction in design inconsistencies, 78% workflow efficiency improvement - 4 core workflows: Frame→Component, Design System Audit, Token Automation, Visual Iteration - 3-tier token hierarchy (base/composite/semantic) - Team adoption patterns for designers, developers, PMs - Implementation roadmap (Foundation → Scaling → Orchestration) - Sources: builder.io, parallelhq.com, composio.dev, vladimirsiedykh.com - New template: examples/claude-md/product-designer.md (400 lines) - Complete CLAUDE.md configuration for design-to-code projects - Figma MCP commands reference - Design handoff checklist - Token conventions and implementation constraints - Updated README.md: Added "Product Designer" learning path (5 steps) - Positioned after DevOps/SRE, before main content - Links to image analysis, wireframing, Figma MCP, new workflow, cheatsheet - Updated machine-readable/reference.yaml: Added 4 new entries - product_designer_workflow, product_designer_claudemd - design_system_handoff, figma_make_integration Templates count: 72 → 73 (examples/claude-md/product-designer.md) Guide workflows: 6 → 7 (guide/workflows/design-to-code.md) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
01f35bf8b7
commit
8c93c31b90
5 changed files with 1139 additions and 0 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -28,3 +28,6 @@ to-ignore/
|
|||
whitepapers/
|
||||
claudedocs/
|
||||
.mcp.json
|
||||
|
||||
# Multi-provider (will be moved to dedicated repo)
|
||||
examples/multi-provider/
|
||||
|
|
|
|||
11
README.md
11
README.md
|
|
@ -144,6 +144,17 @@ Same agentic capabilities as Claude Code, but through a visual interface with no
|
|||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Product Designer</strong> — Design-to-code path (5 steps)</summary>
|
||||
|
||||
1. [Working with Images](./guide/ultimate-guide.md#24-working-with-images) — Image analysis basics
|
||||
2. [Wireframing Tools](./guide/ultimate-guide.md#wireframing-tools) — ASCII/Excalidraw workflows
|
||||
3. [Figma MCP](./guide/ultimate-guide.md#figma-mcp) — Design file access & tokens
|
||||
4. [Design-to-Code Workflow](./guide/workflows/design-to-code.md) — Figma Make → Claude handoff ⭐
|
||||
5. [Cheat Sheet](./guide/cheatsheet.md) — Print this
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📚 What's Inside
|
||||
|
|
|
|||
401
examples/claude-md/product-designer.md
Normal file
401
examples/claude-md/product-designer.md
Normal file
|
|
@ -0,0 +1,401 @@
|
|||
# Product Designer CLAUDE.md Template
|
||||
|
||||
A CLAUDE.md configuration optimized for design-to-code workflows using Figma MCP.
|
||||
|
||||
## Usage
|
||||
|
||||
Copy this content to your project's `CLAUDE.md` file and customize the sections marked with `[brackets]`.
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Product Designer Project Configuration
|
||||
|
||||
## Design System Source
|
||||
|
||||
### Figma Files
|
||||
- Design System Library: [Figma file URL]
|
||||
- Component Library: [Figma file URL]
|
||||
- Current Project: [Figma file URL]
|
||||
|
||||
### Access
|
||||
- Figma MCP configured: Yes/No
|
||||
- Personal Access Token: [Configured in MCP settings - never share value]
|
||||
- Dev Mode access: [Required for full variable inspection]
|
||||
|
||||
## Token Hierarchy
|
||||
|
||||
Our design tokens follow a 3-tier structure:
|
||||
|
||||
### Base Tokens (Primitives)
|
||||
Figma Variables → CSS Custom Properties
|
||||
- Colors: `--blue-600`, `--gray-100`, etc.
|
||||
- Spacing: `--spacing-1` (4px), `--spacing-2` (8px), etc.
|
||||
- Typography: `--font-size-sm`, `--font-weight-medium`, etc.
|
||||
- Radii: `--radius-sm`, `--radius-md`, etc.
|
||||
|
||||
### Composite Tokens
|
||||
Combined primitives used in components
|
||||
- Button padding: `var(--spacing-2) var(--spacing-4)`
|
||||
- Card shadow: `var(--shadow-md)`
|
||||
- Input border: `var(--border-width-1) solid var(--border-default)`
|
||||
|
||||
### Semantic Tokens
|
||||
Context-specific meaning
|
||||
- `--interactive-primary`: Main action color
|
||||
- `--surface-elevated`: Card/modal backgrounds
|
||||
- `--text-secondary`: Descriptive text
|
||||
- `--border-error`: Form validation
|
||||
|
||||
## Design Rules
|
||||
|
||||
### Colors
|
||||
- Primary: [#HEX] → `var(--interactive-primary)`
|
||||
- Secondary: [#HEX] → `var(--interactive-secondary)`
|
||||
- Never use: Hardcoded hex values in components
|
||||
- Always use: Design token variables
|
||||
|
||||
### Spacing
|
||||
- Base unit: [4px/8px]
|
||||
- Scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]
|
||||
- Never use: Magic numbers (e.g., `padding: 13px`)
|
||||
- Always use: Token multiples (e.g., `var(--spacing-3)`)
|
||||
|
||||
### Typography
|
||||
- Font family: [Inter/Roboto/System/Custom]
|
||||
- Scale: [12, 14, 16, 18, 20, 24, 32, 48, 64]
|
||||
- Line heights: [1.2, 1.5, 1.6] depending on text size
|
||||
- Letter spacing: Follow Figma text styles exactly
|
||||
|
||||
### Responsive Breakpoints
|
||||
Match Figma frame sizes:
|
||||
- Mobile: [320-767px]
|
||||
- Tablet: [768-1023px]
|
||||
- Desktop: [1024px+]
|
||||
- Max width: [1440px]
|
||||
|
||||
## Figma MCP Commands
|
||||
|
||||
When I share a Figma URL, you can use these MCP commands:
|
||||
|
||||
### Reading Design Files
|
||||
```
|
||||
figma_get_file(file_key: string)
|
||||
→ Returns: File structure, pages, frames
|
||||
```
|
||||
|
||||
### Extracting Styles
|
||||
```
|
||||
figma_get_styles(file_key: string)
|
||||
→ Returns: Color styles, text styles, effect styles
|
||||
```
|
||||
|
||||
### Fetching Components
|
||||
```
|
||||
figma_get_component(file_key: string, node_id: string)
|
||||
→ Returns: Component properties, variants, design tokens
|
||||
```
|
||||
|
||||
### Variables (Design Tokens)
|
||||
```
|
||||
figma_get_variables(file_key: string)
|
||||
→ Returns: All Figma variables (primitives)
|
||||
```
|
||||
|
||||
## Code Connect Mappings
|
||||
|
||||
We use Figma Code Connect to link designs to code. When implementing components, reference these mappings:
|
||||
|
||||
| Figma Component | Code Path | Notes |
|
||||
|-----------------|-----------|-------|
|
||||
| Button/Primary | `components/Button/Primary.tsx` | Uses `PrimaryButton` component |
|
||||
| Input/Text | `components/Input/Text.tsx` | Supports error states |
|
||||
| Card/Default | `components/Card/index.tsx` | Auto Layout → Flexbox |
|
||||
| Modal/Standard | `components/Modal/Standard.tsx` | Focus trap + A11y |
|
||||
|
||||
[Add your mappings here]
|
||||
|
||||
## Implementation Constraints
|
||||
|
||||
### Technology Stack
|
||||
- Framework: [React/Vue/Svelte/Angular]
|
||||
- Styling: [Tailwind/CSS Modules/Styled Components/CSS-in-JS]
|
||||
- TypeScript: [Required/Optional]
|
||||
- Component library: [Building custom / Using MUI/Chakra/etc.]
|
||||
|
||||
### Patterns
|
||||
- Component structure: [Atomic Design / Feature-based / Flat]
|
||||
- State management: [useState / Context / Redux / Zustand]
|
||||
- Props naming: [Match Figma variants exactly]
|
||||
|
||||
### Quality Requirements
|
||||
- TypeScript types for all props
|
||||
- Accessible by default (WCAG AA minimum)
|
||||
- Responsive behavior matching Figma frames
|
||||
- Hover/focus/disabled states from Figma
|
||||
|
||||
## Design Handoff Checklist
|
||||
|
||||
When you implement a component from Figma, verify:
|
||||
|
||||
### Design Match
|
||||
- [ ] Colors match Figma exactly (use browser DevTools color picker)
|
||||
- [ ] Spacing matches Figma measurements
|
||||
- [ ] Typography (size, weight, line-height) matches
|
||||
- [ ] Border radius matches
|
||||
- [ ] Shadows/effects match
|
||||
|
||||
### Tokens
|
||||
- [ ] No hardcoded colors (all use `var(--token-name)`)
|
||||
- [ ] No magic number spacing
|
||||
- [ ] Font sizes use design tokens
|
||||
- [ ] All values traceable to design system
|
||||
|
||||
### Responsive
|
||||
- [ ] Mobile breakpoint implemented
|
||||
- [ ] Tablet breakpoint implemented
|
||||
- [ ] Desktop layout matches
|
||||
- [ ] No horizontal scroll on mobile
|
||||
|
||||
### Accessibility
|
||||
- [ ] Keyboard navigation works
|
||||
- [ ] Focus states visible
|
||||
- [ ] ARIA labels present where needed
|
||||
- [ ] Color contrast passes WCAG AA
|
||||
- [ ] Screen reader tested (if interactive)
|
||||
|
||||
### States
|
||||
- [ ] Default state implemented
|
||||
- [ ] Hover state matches Figma
|
||||
- [ ] Focus state matches Figma
|
||||
- [ ] Disabled state matches Figma
|
||||
- [ ] Error state (if applicable)
|
||||
- [ ] Loading state (if applicable)
|
||||
|
||||
## Response Preferences
|
||||
|
||||
### For Component Implementation
|
||||
1. Read Figma component via MCP
|
||||
2. Extract all variants and properties
|
||||
3. Map design tokens to code tokens
|
||||
4. Generate TypeScript component with full types
|
||||
5. Include Storybook story (if we use Storybook)
|
||||
6. Verify against checklist above
|
||||
|
||||
### For Design System Audits
|
||||
1. Compare codebase against Figma source of truth
|
||||
2. Report hardcoded values (colors, spacing, etc.)
|
||||
3. Flag inconsistencies (missing variants, wrong tokens)
|
||||
4. Propose automated fixes
|
||||
|
||||
### For Token Updates
|
||||
1. When design tokens change in Figma, notify about affected components
|
||||
2. Generate migration script if breaking changes
|
||||
3. Verify no hardcoded values will break
|
||||
|
||||
## Team Conventions
|
||||
|
||||
### Commit Messages
|
||||
- Format: `feat(ui): add Button component from Figma`
|
||||
- Reference Figma frame: `feat(ui): implement Modal (Figma frame: abc123)`
|
||||
|
||||
### PR Requirements
|
||||
- [ ] Screenshot comparison (code vs Figma)
|
||||
- [ ] All checklist items verified
|
||||
- [ ] Responsive behavior tested
|
||||
- [ ] Accessibility verified
|
||||
|
||||
### Component Documentation
|
||||
Each component should document:
|
||||
- Figma source (URL + frame ID)
|
||||
- When last synced with design
|
||||
- Any deviations from design (with rationale)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### For React + Tailwind Projects
|
||||
|
||||
Add to "Technology Stack":
|
||||
```markdown
|
||||
### Tailwind Configuration
|
||||
- Config file: `tailwind.config.ts`
|
||||
- Custom utilities: `src/styles/utilities.css`
|
||||
- Design tokens mapped in: `theme.extend` object
|
||||
|
||||
### Component Pattern
|
||||
```tsx
|
||||
// components/Button/Primary.tsx
|
||||
import { cn } from '@/lib/utils';
|
||||
|
||||
interface ButtonProps {
|
||||
size?: 'sm' | 'md' | 'lg';
|
||||
disabled?: boolean;
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export function PrimaryButton({ size = 'md', disabled, children }: ButtonProps) {
|
||||
return (
|
||||
<button
|
||||
className={cn(
|
||||
// Base styles
|
||||
'rounded-md font-medium transition-colors',
|
||||
// Semantic tokens
|
||||
'bg-interactive-primary text-white',
|
||||
'hover:bg-interactive-primary-hover',
|
||||
// States
|
||||
'disabled:opacity-50 disabled:cursor-not-allowed',
|
||||
// Size variants
|
||||
{
|
||||
'px-3 py-1.5 text-sm': size === 'sm',
|
||||
'px-4 py-2 text-base': size === 'md',
|
||||
'px-6 py-3 text-lg': size === 'lg',
|
||||
}
|
||||
)}
|
||||
disabled={disabled}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### For Design System with Tokens Studio
|
||||
|
||||
Add section:
|
||||
```markdown
|
||||
## Token Automation
|
||||
|
||||
### Tokens Studio Setup
|
||||
- Plugin connected to: [GitHub repo URL]
|
||||
- Branch: `design-tokens`
|
||||
- Sync frequency: [On save / Manual / CI/CD]
|
||||
|
||||
### Token Export Format
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"blue": {
|
||||
"600": {
|
||||
"value": "#0066CC",
|
||||
"type": "color"
|
||||
}
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"2": {
|
||||
"value": "8px",
|
||||
"type": "spacing"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Style Dictionary Transform
|
||||
- Config: `style-dictionary.config.js`
|
||||
- Output: `src/tokens/` directory
|
||||
- Platforms: CSS, Tailwind, iOS, Android
|
||||
```
|
||||
|
||||
### For Teams Using Storybook
|
||||
|
||||
Add to "Response Preferences":
|
||||
```markdown
|
||||
### For Storybook Stories
|
||||
Generate stories with all variants:
|
||||
|
||||
```tsx
|
||||
// Button.stories.tsx
|
||||
import type { Meta, StoryObj } from '@storybook/react';
|
||||
import { PrimaryButton } from './Primary';
|
||||
|
||||
const meta: Meta<typeof PrimaryButton> = {
|
||||
title: 'Components/Button/Primary',
|
||||
component: PrimaryButton,
|
||||
parameters: {
|
||||
design: {
|
||||
type: 'figma',
|
||||
url: 'https://www.figma.com/file/[FILE_KEY]?node-id=[NODE_ID]',
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
export default meta;
|
||||
type Story = StoryObj<typeof PrimaryButton>;
|
||||
|
||||
export const Default: Story = {
|
||||
args: {
|
||||
children: 'Click me',
|
||||
size: 'md',
|
||||
},
|
||||
};
|
||||
|
||||
export const Small: Story = {
|
||||
args: {
|
||||
children: 'Small button',
|
||||
size: 'sm',
|
||||
},
|
||||
};
|
||||
|
||||
// ... all variants from Figma
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Workflows
|
||||
|
||||
This CLAUDE.md pairs with the Design-to-Code workflow:
|
||||
|
||||
- Read: [Design-to-Code Workflow](../../guide/workflows/design-to-code.md)
|
||||
- Understand: Figma Make → Claude MCP → Production pipeline
|
||||
- Apply: Use this config to maintain design-code parity
|
||||
|
||||
---
|
||||
|
||||
## Example Prompts
|
||||
|
||||
### Implement Component from Figma
|
||||
```
|
||||
Implement the "Card/Product" component from our Figma design system:
|
||||
[Figma URL]
|
||||
|
||||
Follow the design handoff checklist.
|
||||
Use our token conventions from this CLAUDE.md.
|
||||
Generate TypeScript component with all variants.
|
||||
```
|
||||
|
||||
### Audit Design System Drift
|
||||
```
|
||||
Audit src/components against our Figma design system:
|
||||
[Figma URL]
|
||||
|
||||
Report:
|
||||
1. Hardcoded values not using tokens
|
||||
2. Missing variants present in Figma
|
||||
3. Inconsistent spacing/colors
|
||||
4. Propose fixes
|
||||
```
|
||||
|
||||
### Update Component After Design Change
|
||||
```
|
||||
The Button component was updated in Figma:
|
||||
[Figma URL → Button frame]
|
||||
|
||||
Review changes, update code to match.
|
||||
Ensure backward compatibility if possible.
|
||||
Update Storybook stories if needed.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Design-to-Code Workflow](../../guide/workflows/design-to-code.md) — Complete Figma MCP workflow guide
|
||||
- [Figma MCP Section](../../guide/ultimate-guide.md#figma-mcp) — Technical details
|
||||
- [Working with Images](../../guide/ultimate-guide.md#24-working-with-images) — Visual analysis basics
|
||||
719
guide/workflows/design-to-code.md
Normal file
719
guide/workflows/design-to-code.md
Normal file
|
|
@ -0,0 +1,719 @@
|
|||
# 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 (
|
||||
<button
|
||||
className={cn(
|
||||
'rounded-md font-medium transition-colors',
|
||||
'bg-interactive-primary text-white',
|
||||
'hover:bg-interactive-primary-hover',
|
||||
'disabled:opacity-50 disabled:cursor-not-allowed',
|
||||
{
|
||||
'px-3 py-1.5 text-sm': size === 'sm',
|
||||
'px-4 py-2 text-base': size === 'md',
|
||||
'px-6 py-3 text-lg': size === 'lg',
|
||||
}
|
||||
)}
|
||||
disabled={disabled}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
<Button variant="primary" size="lg">
|
||||
Click me
|
||||
</Button>
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
|
@ -105,6 +105,11 @@ deep_dive:
|
|||
devops_quick_reference: "guide/devops-sre.md:750"
|
||||
devops_agent: "examples/agents/devops-sre.md"
|
||||
devops_claude_md: "examples/claude-md/devops-sre.md"
|
||||
# Product Designer (design-to-code workflow)
|
||||
product_designer_workflow: "guide/workflows/design-to-code.md"
|
||||
product_designer_claudemd: "examples/claude-md/product-designer.md"
|
||||
design_system_handoff: "guide/workflows/design-to-code.md:531"
|
||||
figma_make_integration: "guide/workflows/design-to-code.md:26"
|
||||
commands: 4950
|
||||
command_template: 5020
|
||||
hooks: 5273
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue