# Figma MCP

**Category:** Integration Tool  
**Purpose:** MCP server for automated Figma integration with WDS  
**Repository:** WDS Figma MCP Server

---

## What It Is

Figma MCP (Model Context Protocol) is a server that enables automated, bidirectional communication between WDS agents (Freya) and Figma. It allows precise component-level injection from HTML prototypes into Figma and automated reading of refined components back into the design system.

---

## Why WDS Recommends It

**Automation:**
- Freya automatically injects components to Figma
- No manual upload or conversion needed
- Automated design token extraction
- Bidirectional sync (Prototype ↔ Figma ↔ Design System)

**Precision:**
- Component-level injection (not full pages)
- Object ID preservation automatic
- Target specific Figma pages
- Batch component operations

**Integration:**
- Seamless WDS workflow integration
- Page naming matches specification structure
- Automated design system updates
- Version control friendly

---

## Setup Instructions

### 1. Installation

```bash
# Install Figma MCP server
npm install -g @wds/figma-mcp-server
```

### 2. Figma API Access

Get your Figma personal access token:

1. Go to Figma Settings → Account
2. Scroll to "Personal access tokens"
3. Click "Generate new token"
4. Name it "WDS MCP Server"
5. Copy the token

### 3. Configuration

Set up environment variables:

```bash
# Set Figma access token
export FIGMA_ACCESS_TOKEN="your-token-here"

# Or create .env file
echo "FIGMA_ACCESS_TOKEN=your-token-here" > .env
```

Create MCP configuration file:

`.wds/figma-mcp-config.yaml`:
```yaml
figma:
  access_token: ${FIGMA_ACCESS_TOKEN}
  default_file_id: "your-figma-file-id"
  default_page: "WDS Components"
  
extraction:
  preserve_object_ids: true
  extract_design_tokens: true
  convert_to_components: true
  maintain_hierarchy: true
  
injection:
  auto_layout: true
  responsive_constraints: true
  component_naming: "object-id"
  page_naming: "scenario-page"
  
sync:
  bidirectional: true
  auto_update_design_system: false
  conflict_resolution: "manual"

naming_conventions:
  page_format: "{scenario-number}-{scenario-name} / {page-number}-{page-name}"
  example: "01-Customer-Onboarding / 1.2-Sign-In"
  source: "docs/C-Scenarios/"
```

### 4. Initialize MCP Server

```bash
# Initialize for your project
wds figma init

# Test connection
wds figma test-connection
```

### 5. Get Figma File ID

From your Figma file URL:
```
https://figma.com/file/ABC123DEF456/Project-Name
                        ^^^^^^^^^^^^
                        This is your file ID
```

---

## Freya's Automated Workflow

### Phase 1: Injection (Automated by Freya)

```
User: "Prototype needs refinement"
    ↓
Freya analyzes prototype components
    ↓
Freya identifies components needing refinement
    ↓
Freya presents options to user
    ↓
User: "Yes, inject to Figma"
    ↓
Freya automatically:
  - Determines target Figma file from config
  - Creates/navigates to matching page
  - Injects selected components via MCP
  - Preserves Object IDs in layer names
  - Provides Figma link to user
```

### Phase 2: Reading Back (Automated by Freya)

```
User: "Finished refining in Figma"
    ↓
Freya automatically:
  - Connects to Figma via MCP
  - Reads refined components
  - Extracts design tokens
  - Identifies variants and states
  - Presents changes to user
    ↓
User: "Update design system"
    ↓
Freya automatically:
  - Updates design system files
  - Creates/updates component docs
  - Updates design tokens
  - Offers to re-render prototype
```

---

## WDS Best Practices

### DO ✅

**1. Use Freya Automation**
- Let Freya handle injection automatically
- Freya analyzes components and determines what to inject
- Freya reads refined components back
- No manual commands needed

**2. Maintain Object ID Traceability**
- All components have Object IDs in HTML
- MCP preserves Object IDs in Figma layer names
- Enables tracking from spec → prototype → Figma → design system

**3. Follow Page Naming Convention**
- Pages match WDS specification structure
- Format: `[Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]`
- Example: `01-Customer-Onboarding / 1.2-Sign-In`

**4. Batch Related Components**
- Inject related components together
- Maintains context for designer
- Efficient workflow

### DON'T ❌

**1. Don't Inject Entire Pages**
- Use component-level precision
- Inject only what needs refinement
- Avoid unnecessary extraction

**2. Don't Skip Object IDs**
- Always include Object IDs in HTML
- Required for traceability
- Enables automated mapping

**3. Don't Manually Upload**
- Use MCP server, not manual upload
- Automation is more reliable
- Maintains consistency

---

## Troubleshooting

### Issue: MCP server can't connect to Figma

**Solution:**
```bash
# Verify access token
echo $FIGMA_ACCESS_TOKEN

# Test connection
wds figma test-connection

# Check Figma file permissions
# Ensure token has access to file
```

### Issue: Components not injecting

**Solution:**
- Verify Object IDs exist in HTML
- Check Figma file ID in config
- Ensure page name is correct
- Check MCP server logs

### Issue: Design tokens not extracting

**Solution:**
- Ensure Figma uses variables (not hardcoded values)
- Check extraction settings in config
- Verify component has proper styling
- Review MCP server logs

### Issue: Object IDs not preserved

**Solution:**
- Check `preserve_object_ids: true` in config
- Verify Object IDs in HTML data attributes
- Ensure MCP server version is up to date

---

## Security Best Practices

### DO ✅

**1. Protect Access Token**
```bash
# Use environment variables
export FIGMA_ACCESS_TOKEN="token"

# Or .env file (add to .gitignore)
echo "FIGMA_ACCESS_TOKEN=token" > .env
```

**2. Add to .gitignore**
```gitignore
.env
.wds/figma-mcp-config.yaml  # If contains sensitive data
```

**3. Use Separate Tokens**
- Different tokens for dev/production
- Rotate tokens periodically
- Revoke unused tokens

### DON'T ❌

**1. Don't Commit Tokens**
- Never commit access tokens to git
- Don't hardcode in configuration files
- Don't share tokens in documentation

**2. Don't Use Personal Tokens for Team**
- Create team/project-specific tokens
- Use service accounts when available
- Track token usage

---

## Advantages Over Manual Methods

**vs. html.to.design:**
- ✅ Component-level precision (not full page)
- ✅ Automated Object ID preservation
- ✅ Bidirectional sync
- ✅ Batch operations
- ✅ Freya integration

**vs. Manual Figma Creation:**
- ✅ Faster workflow
- ✅ Maintains code-design sync
- ✅ Automated token extraction
- ✅ Consistent structure
- ✅ Reduced manual work

---

## Resources

**Documentation:**
- MCP Server Integration Guide: `workflows/5-design-system/figma-integration/mcp-server-integration.md`
- Prototype to Figma Workflow: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md`

**Configuration:**
- Example config: `.wds/figma-mcp-config.yaml`
- Environment setup: `.env.example`

**Support:**
- Figma API Docs: <https://www.figma.com/developers/api>
- Check MCP server logs for errors
- Contact WDS team for integration issues

---

[← Back to Tools](wds-tools-guide.md)