ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/src/modules/wds/docs/tools/figma-mcp.md

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

  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:

# 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

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:

← Back to Tools