11 KiB

Raw Blame History

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

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

2. Figma API Access

Get your Figma personal access token:

Go to Figma Settings → Account
Scroll to "Personal access tokens"
Click "Generate new token"
Name it "WDS MCP Server"
Copy the token

3. Configuration

Set up environment variables:

# 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:

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

# 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:

# 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

# Use environment variables
export FIGMA_ACCESS_TOKEN="token"

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

2. Add to .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

Windsurf IDE Integration (Official Figma MCP)

Overview

The official Figma Desktop MCP server provides read-only access to Figma files through Windsurf IDE. This enables AI agents like Freya to directly extract design definitions from Figma without manual copying.

Prerequisites

Figma Account: Paid account with Dev Mode access
Figma Desktop: Latest version installed
Windsurf IDE: With MCP support enabled

Configuration

1. MCP Config File

Location: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "Figma Desktop": {
      "serverUrl": "http://127.0.0.1:3845/mcp"
    }
  }
}

Important: Use serverUrl (not url) for HTTP-based MCP servers in Windsurf.

2. Figma Desktop Setup

Open Figma Desktop with your paid account
The official Figma MCP server runs automatically on port 3845
Open your design file
Select the node/frame you want to extract

3. Windsurf Configuration

Open Windsurf Settings: Ctrl+, (or Cmd+, on Mac)
Navigate to: Tools → Windsurf Settings → MCP Servers
Click the refresh button after modifying mcp_config.json
Verify "Figma Desktop" appears as Enabled

Available Tools

The Figma Desktop MCP server provides:

get_design_context - Extract full design context including code, styles, and assets
get_variable_defs - Get design variable definitions
get_screenshot - Capture visual screenshot of selected node
get_metadata - Get structural metadata in XML format
create_design_system_rules - Generate design system rules
get_figjam - Extract FigJam board content

Usage Example

Extracting Color Definitions:

In Figma Desktop: Select the color palette frame
In Windsurf: Call the MCP tool:

mcp1_get_design_context(
  clientLanguages: "markdown",
  clientFrameworks: "unknown",
  nodeId: "",  // Empty for currently selected node
  dirForAssetWrites: "path/to/assets"
)

Result: Receives React/Tailwind code with all color values, which can be parsed and converted to design tokens

Getting Visual Reference:

mcp1_get_screenshot(
  clientLanguages: "markdown",
  clientFrameworks: "unknown",
  nodeId: ""
)

Real-World Success: Dogweek Design System

Date: January 9, 2026

Successfully extracted the Dogweek color system from Figma and integrated into project design system:

10 Primary Colors: Brand colors, semantic colors (success, error, info)
7 Gradient Definitions: For rich visual effects
Typography: Font family specifications (Fredoka, Liberation Sans)

The extracted data was automatically converted from React/Tailwind format to structured markdown documentation in the Dogweek project.

Troubleshooting

Issue: "Nothing is selected"

Solution: Select a node in Figma Desktop before calling MCP tools

Issue: "Path for asset writes required"

Solution: Provide dirForAssetWrites parameter with absolute path

Issue: "Failed to initialize server"

Solution:
- Ensure Figma Desktop is running
- Verify you're logged into a paid account with Dev Mode access
- Check that port 3845 is not blocked

Issue: MCP server not appearing in Windsurf

Solution:
- Use serverUrl instead of url in config
- Click refresh button in MCP settings
- Restart Windsurf completely

Benefits for WDS Method

Automated Design Token Extraction: No manual copying of color codes, spacing values, etc.
Single Source of Truth: Design definitions come directly from Figma
Version Control: Changes in Figma can be re-extracted and documented
AI Agent Integration: Freya can reference actual design system values
Reduced Human Error: Eliminates transcription mistakes

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

11 KiB Raw Blame History

Figma MCP

What It Is

Why WDS Recommends It

Setup Instructions

1. Installation

2. Figma API Access

3. Configuration

4. Initialize MCP Server

5. Get Figma File ID

Freya's Automated Workflow

Phase 1: Injection (Automated by Freya)

Phase 2: Reading Back (Automated by Freya)

WDS Best Practices

DO ✅

DON'T ❌

Troubleshooting

Issue: MCP server can't connect to Figma

Issue: Components not injecting

Issue: Design tokens not extracting

Issue: Object IDs not preserved

Security Best Practices

DO ✅

DON'T ❌

Advantages Over Manual Methods

Windsurf IDE Integration (Official Figma MCP)

Overview

Prerequisites

Configuration

Available Tools

Usage Example

Real-World Success: Dogweek Design System

Troubleshooting

Benefits for WDS Method

Resources

11 KiB

Raw Blame History