bi-agents/_bmad/wds/workflows/6-asset-generation/data/figma-mcp-integration.md

Figma MCP Integration for WDS

Purpose: Technical guide for integrating Figma with WDS using Model Context Protocol (MCP).

Audience: AI agents, developers, technical designers

---

Overview

Figma MCP enables:

• Reading component specifications from Figma
• Extracting design tokens
• Generating WDS component specifications
• Maintaining Figma ↔ WDS sync

---

MCP Server Setup

Prerequisites

• Figma API access token
• MCP server configured
• WDS project initialized
• Design system mode set to "custom"

---

Configuration

Add to MCP configuration:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-figma"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-figma-token"
      }
    }
  }
}

Get Figma API token:

1. Go to Figma → Settings → Account
2. Scroll to "Personal access tokens"
3. Click "Generate new token"
4. Copy token and add to configuration

---

MCP Operations

1. Read Figma Component

Purpose: Extract component data from Figma

Input:

• Figma file ID
• Node ID
• Or component name

Output:

• Component structure
• Variants
• Properties
• Design tokens used

Example:

Agent: Read Figma component Button/Primary

MCP Response:
{
  "name": "Button/Primary [btn-001]",
  "type": "COMPONENT_SET",
  "variants": [
    {
      "name": "Type=Primary, Size=Medium, State=Default",
      "properties": {
        "Type": "Primary",
        "Size": "Medium",
        "State": "Default"
      },
      "styles": {
        "background": "primary/600",
        "padding": "16px 12px",
        "borderRadius": "8px"
      }
    },
    // ... more variants
  ],
  "description": "Button Primary [btn-001]...",
  "nodeId": "456:789"
}

---

2. Extract Design Tokens

Purpose: Get design token values from Figma

Input:

• Figma file ID
• Token type (colors, typography, spacing)

Output:

• Token definitions
• Token values
• Token mappings

Example:

Agent: Extract color tokens from Figma

MCP Response:
{
  "colors": {
    "primary/50": "#eff6ff",
    "primary/500": "#3b82f6",
    "primary/600": "#2563eb",
    "gray/900": "#111827"
  }
}

---

3. Get Component Node ID

Purpose: Find Figma node ID for component

Input:

• Component name or WDS component ID

Output:

• Figma node ID
• File ID
• Full Figma URL

Example:

Agent: Get node ID for Button [btn-001]

MCP Response:
{
  "componentId": "btn-001",
  "fileId": "abc123",
  "nodeId": "456:789",
  "url": "figma://file/abc123/node/456:789"
}

---

4. List Components

Purpose: Get all components in Figma file

Input:

• Figma file ID
• Optional: filter by type

Output:

• List of components
• Component names
• Node IDs

Example:

Agent: List all button components

MCP Response:
{
  "components": [
    {
      "name": "Button/Primary [btn-001]",
      "nodeId": "456:789",
      "type": "COMPONENT_SET"
    },
    {
      "name": "Button/Secondary [btn-001]",
      "nodeId": "456:790",
      "type": "COMPONENT_SET"
    }
  ]
}

---

Sync Workflows

Figma → WDS Sync

When: Component created or updated in Figma

Process:

Step 1: Detect Change

Designer updates Button/Primary in Figma
Designer notifies WDS system
Or: Automated webhook triggers sync

Step 2: Read Component

Agent: Read Figma component Button/Primary [btn-001]

MCP reads:
- Component structure
- All variants
- All states
- Properties
- Design tokens
- Description

Step 3: Parse Component Data

Agent extracts:
- Component type: Button
- WDS ID: btn-001
- Variants: primary, secondary, ghost
- States: default, hover, active, disabled, loading
- Sizes: small, medium, large
- Design tokens: primary/600, spacing/4, radius/md

Step 4: Generate WDS Specification

Agent creates/updates:
D-Design-System/components/button.md

Using template: component.template.md
Filling in:
- Component name and ID
- Variants from Figma
- States from Figma
- Styling from design tokens
- Description from Figma

Step 5: Update Mappings

Agent updates:
D-Design-System/figma-mappings.md

Adds/updates:
Button [btn-001] → figma://file/abc123/node/456:789

Step 6: Verify and Confirm

Agent presents generated spec to designer
Designer reviews and confirms
Spec is committed to repository

---

WDS → Figma Notification

When: WDS specification updated

Process:

Step 1: Detect Change

WDS specification updated
Git commit triggers notification

Step 2: Identify Figma Component

Agent reads figma-mappings.md
Finds: Button [btn-001] → figma://file/abc123/node/456:789

Step 3: Notify Designer

Agent creates notification:
"Button [btn-001] specification updated in WDS.
Please review and update Figma component if needed.

Changes:
- Added new loading state
- Updated hover animation
- Modified padding values

Figma component: [Link to Figma]"

Step 4: Designer Updates Figma

Designer reviews changes
Updates Figma component
Confirms sync complete

Note: Full WDS → Figma automation requires Figma API write access (currently read-only for MCP).

---

Component Specification Generation

Template-Based Generation

Agent uses component template:

Input:

Figma component data:
{
  "name": "Button/Primary [btn-001]",
  "variants": [...],
  "states": [...],
  "tokens": {...},
  "description": "..."
}

Template: templates/component.template.md

Output: D-Design-System/components/button.md

Process:

1. Load component template
2. Fill in component name and ID
3. Extract and format variants
4. Extract and format states
5. Map design tokens to WDS tokens
6. Add styling specifications
7. Include description and usage
8. Generate accessibility notes
9. Add version history
10. Save to design system folder

---

Token Mapping

Figma variables → WDS tokens:

Agent maps:

Figma: primary/600 → WDS: color-primary-600
Figma: spacing/4 → WDS: spacing-4
Figma: Text/Body → WDS: text-body
Figma: shadow/sm → WDS: shadow-sm

Mapping rules:

• Figma collection/variable → WDS category-name-value
• Maintain semantic meaning
• Consistent naming across systems
• Document custom mappings

---

Error Handling

Component Not Found

Error: Figma component doesn't exist

Agent response:

⚠️ Component not found in Figma

Component: Button/Primary [btn-001]
File ID: abc123
Node ID: 456:789

Possible causes:
- Component deleted in Figma
- Node ID changed
- File ID incorrect
- Access permissions

Actions:
1. Verify component exists in Figma
2. Update node ID in figma-mappings.md
3. Re-sync component

---

Missing WDS Component ID

Error: Figma component has no WDS ID in description

Agent response:

⚠️ WDS Component ID missing

Component: Button/Primary
Figma node: 456:789

Please add WDS component ID to Figma description:
Format: [component-id]
Example: Button/Primary [btn-001]

After adding ID, re-sync component.

---

Token Mapping Failure

Error: Can't map Figma variable to WDS token

Agent response:

⚠️ Token mapping failed

Figma variable: custom-blue-500
No matching WDS token found

Options:
1. Create new WDS token: color-custom-blue-500
2. Map to existing token: color-primary-500
3. Add custom mapping rule

Your choice:

---

Sync Conflict

Error: Figma and WDS have different versions

Agent response:

⚠️ Sync conflict detected

Component: Button [btn-001]

Figma version:
- Last updated: 2024-12-15
- Changes: Added loading state

WDS version:
- Last updated: 2024-12-14
- Changes: Updated hover animation

Options:
1. Figma wins (overwrite WDS)
2. WDS wins (notify designer)
3. Manual merge (review both)

Your choice:

---

Best Practices

For AI Agents

DO ✅

• Always check for WDS component ID in Figma
• Verify token mappings before generating specs
• Present generated specs for designer review
• Update figma-mappings.md after sync
• Document sync operations in version history

DON'T ❌

• Don't overwrite WDS specs without confirmation
• Don't create components without designer approval
• Don't skip token mapping validation
• Don't ignore sync conflicts
• Don't forget to update mappings

---

For Designers

DO ✅

• Add WDS component ID to all Figma components
• Use design tokens (variables) consistently
• Document component changes
• Notify system when updating components
• Review generated specs before committing

DON'T ❌

• Don't use hardcoded values
• Don't skip component descriptions
• Don't forget to sync after changes
• Don't detach component instances
• Don't change component IDs

---

Integration Points

Phase 4: UX Design

When component is specified in Phase 4:

1. Designer creates sketch
2. Agent specifies component
3. Design system router checks for similar components
4. If new component needed:
   • Designer creates in Figma
   • MCP reads from Figma
   • Spec generated automatically

---

Phase 5: Design System

When component is added to design system:

1. Component specification complete
2. Agent checks: Figma component exists?
3. If yes:
   • MCP reads Figma component
   • Extracts styling details
   • Updates WDS spec with Figma data
4. If no:
   • Designer creates in Figma
   • MCP syncs to WDS

---

Command Reference

Read Component

Agent: Read Figma component [component-name]
MCP: Returns component data

Extract Tokens

Agent: Extract [token-type] tokens from Figma
MCP: Returns token definitions

Get Node ID

Agent: Get Figma node ID for [component-id]
MCP: Returns node ID and URL

List Components

Agent: List Figma components [optional: filter]
MCP: Returns component list

Sync Component

Agent: Sync Figma component [component-name] to WDS
MCP: Reads component, generates spec, updates mappings

---

Troubleshooting

MCP Server Not Responding

Check:

• MCP server is running
• Figma API token is valid
• Network connection is active
• File ID and node ID are correct

---

Invalid API Token

Error: 403 Forbidden

Solution:

1. Generate new Figma API token
2. Update MCP configuration
3. Restart MCP server
4. Retry operation

---

Rate Limiting

Error: 429 Too Many Requests

Solution:

• Wait before retrying
• Batch operations when possible
• Cache component data
• Reduce sync frequency

---

Future Enhancements

Planned features:

• Automated sync on Figma changes (webhooks)
• Bidirectional sync (WDS → Figma write)
• Batch component import
• Design token extraction automation
• Component usage tracking from Figma
• Visual diff for sync conflicts

---

This MCP integration enables seamless Figma ↔ WDS synchronization while maintaining designer control and design system consistency.