cassel/calctext

Fork 0

Files

C. Cassel bfe0e01254 initial commit

2026-03-16 19:54:53 -04:00

11 KiB

Raw Blame History

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:

Go to Figma → Settings → Account
Scroll to "Personal access tokens"
Click "Generate new token"
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:

Load component template
Fill in component name and ID
Extract and format variants
Extract and format states
Map design tokens to WDS tokens
Add styling specifications
Include description and usage
Generate accessibility notes
Add version history
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:

Designer creates sketch
Agent specifies component
Design system router checks for similar components
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:

Component specification complete
Agent checks: Figma component exists?
If yes:
- MCP reads Figma component
- Extracts styling details
- Updates WDS spec with Figma data
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:

Generate new Figma API token
Update MCP configuration
Restart MCP server
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.

11 KiB Raw Blame History

Figma MCP Integration for WDS

Overview

MCP Server Setup

Prerequisites

Configuration

MCP Operations

1. Read Figma Component

2. Extract Design Tokens

3. Get Component Node ID

4. List Components

Sync Workflows

Figma → WDS Sync

WDS → Figma Notification

Component Specification Generation

Template-Based Generation

Token Mapping

Error Handling

Component Not Found

Missing WDS Component ID

Token Mapping Failure

Sync Conflict

Best Practices

For AI Agents

For Designers

Integration Points

Phase 4: UX Design

Phase 5: Design System

Command Reference

Read Component

Extract Tokens

Get Node ID

List Components

Sync Component

Troubleshooting

MCP Server Not Responding

Invalid API Token

Rate Limiting

Future Enhancements

11 KiB

Raw Blame History