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

MCP Server Integration for Prototype-to-Figma Workflow

Purpose: Enable precise component injection from HTML prototypes into Figma using MCP server.

Key Advantage: Component-level precision - inject exactly what needs refinement, not entire pages.

---

Overview

The MCP (Model Context Protocol) server integration enables WDS to communicate directly with Figma, allowing:

• Selective component extraction from HTML prototypes
• Direct injection into specific Figma files/pages
• Object ID preservation for traceability
• Automated mapping between code and design
• Batch operations for multiple components

---

Architecture

Component Flow

HTML Prototype (with Object IDs)
    ↓
WDS Agent identifies components to extract
    ↓
MCP Server reads HTML/CSS for selected components
    ↓
Converts to Figma-compatible format
    ↓
Injects into target Figma file/page
    ↓
Designer refines in Figma
    ↓
MCP Server reads refined design
    ↓
Updates WDS Design System
    ↓
Re-render prototype with enhanced design system

MCP Server Role

Bidirectional Bridge:

• WDS → Figma: Inject components for refinement
• Figma → WDS: Read refined components back

Capabilities:

• Read HTML/CSS structure
• Convert to Figma nodes
• Create frames, auto-layout, text layers
• Apply styling (colors, spacing, typography)
• Preserve Object IDs in layer names
• Read Figma component definitions
• Extract design tokens
• Map component variants

---

Commands

Extract Component to Figma

Command:

wds figma inject <component-id> [options]

Parameters:

• component-id: Object ID of component to extract (e.g., "btn-login-submit")
• --file <file-id>: Target Figma file ID
• --page <page-name>: Target page within Figma file
• --position <x,y>: Position to inject component (optional)
• --batch <file>: Extract multiple components from list

Example:

# Inject single component (page name matches specification)
wds figma inject btn-login-submit --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In"

# Inject multiple components to same scenario/page
wds figma inject --batch components-to-refine.txt --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In"

Page Naming Convention:

• Format: [Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]
• Example: 01-Customer-Onboarding / 1.2-Sign-In
• Matches WDS specification structure in docs/C-UX-Scenarios/
• Maintains traceability from spec → prototype → Figma

Output:

✓ Component btn-login-submit extracted from prototype
✓ Converted to Figma format
✓ Injected into Figma file abc123, page "Login Components"
✓ Object ID preserved in layer name
✓ Position: (100, 200)

---

Extract Section to Figma

Command:

wds figma inject-section <section-name> [options]

Parameters:

• section-name: Section identifier from specification
• --file <file-id>: Target Figma file ID
• --page <page-name>: Target page within Figma file
• --include-children: Include all child components

Example:

# Inject entire login form section
wds figma inject-section login-form --file abc123 --include-children

---

Read Refined Component from Figma

Command:

wds figma read <component-id> [options]

Parameters:

• component-id: Object ID of component in Figma
• --file <file-id>: Source Figma file ID
• --extract-tokens: Extract design tokens
• --update-design-system: Automatically update design system

Example:

# Read refined component and update design system
wds figma read btn-login-submit --file abc123 --extract-tokens --update-design-system

Output:

✓ Component btn-login-submit read from Figma
✓ Design tokens extracted:
  - Background: primary.600
  - Text: neutral.50
  - Padding: spacing.md spacing.lg
  - Border-radius: radius.md
✓ Design system updated: D-Design-System/components/button.md

---

Batch Operations

Command:

wds figma batch <operation> --list <file>

Operations:

• inject: Inject multiple components
• read: Read multiple refined components
• sync: Bidirectional sync

Example batch file (components-to-refine.txt):

btn-login-submit
btn-signup-cta
input-email
input-password
link-forgot-password

Command:

wds figma batch inject --list components-to-refine.txt --file abc123

---

Workflow Integration

Phase 4D: After Prototype Creation

Agent workflow:

1. Prototype created and tested
2. Visual quality assessment
3. If needs refinement:
   a. Identify components that need polish
   b. Generate component list
   c. Offer to inject to Figma
   d. Execute MCP injection
   e. Provide Figma link to designer

Agent dialogue:

I've identified 5 components that could benefit from visual refinement:
- Login button (btn-login-submit)
- Email input (input-email)
- Password input (input-password)
- Forgot password link (link-forgot-password)
- Sign up CTA (btn-signup-cta)

Would you like me to inject these into Figma for refinement?

[Y] Yes, inject all
[S] Select specific components
[N] No, continue as-is

Choice:

---

Phase 5: Reading Refined Components

Agent workflow:

1. Designer completes refinement in Figma
2. Designer notifies agent
3. Agent reads refined components via MCP
4. Extracts design tokens
5. Updates design system
6. Offers to re-render prototype

Agent dialogue:

I see you've refined the components in Figma. Let me read them back:

Reading btn-login-submit... ✓
Reading input-email... ✓
Reading input-password... ✓
Reading link-forgot-password... ✓
Reading btn-signup-cta... ✓

Design tokens extracted:
- 3 new colors added to palette
- 2 new spacing values defined
- 1 new typography style created

Design system updated:
- Button component enhanced
- Input component refined
- Link component created

Would you like me to re-render the prototype with these improvements?

[Y] Yes, re-render now
[R] Review changes first
[L] Re-render later

Choice:

---

MCP Server Configuration

Setup

1. Install MCP Server

npm install -g @wds/figma-mcp-server

2. Configure Figma API Access

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

# Or in .env file
FIGMA_ACCESS_TOKEN=your-token-here

3. Initialize MCP Server

wds figma init

4. Test Connection

wds figma test-connection

---

Configuration File

Location: .wds/figma-mcp-config.yaml

figma:
  access_token: ${FIGMA_ACCESS_TOKEN}
  default_file_id: "abc123def456"
  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"  # Matches WDS spec structure
  
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-UX-Scenarios/"

---

Figma File Organization

Recommended Structure

Figma file should mirror WDS specification structure:

[Project Name] Design Refinement
├── 01-Customer-Onboarding/
│   ├── 1.1-Start-Page
│   ├── 1.2-Sign-In
│   ├── 1.3-Sign-Up
│   └── ...
├── 02-Family-Management/
│   ├── 2.1-Family-Dashboard
│   ├── 2.2-Add-Member
│   └── ...
└── Components/
    ├── Buttons
    ├── Inputs
    └── Cards

Benefits:

• Direct mapping to WDS specifications
• Easy to locate components by scenario/page
• Maintains project structure consistency
• Clear handoff to developers

Page Naming:

• Use exact scenario and page numbers from specs
• Format: [Number]-[Name] (e.g., 1.2-Sign-In)
• Matches folder structure in docs/C-UX-Scenarios/

---

Component Selection Strategies

Strategy 1: Individual Components

When to use: Specific components need refinement

Process:

# Inject one component at a time
wds figma inject btn-login-submit --file abc123
wds figma inject input-email --file abc123

Advantages:

• Precise control
• Focused refinement
• Easy to track changes

---

Strategy 2: Component Groups

When to use: Related components need consistent refinement

Process:

# Create component group file
echo "btn-login-submit
btn-signup-cta
btn-cancel" > login-buttons.txt

# Inject group
wds figma batch inject --list login-buttons.txt --file abc123

Advantages:

• Consistent design decisions
• Efficient batch processing
• Related components together

---

Strategy 3: Section-Based

When to use: Entire section needs refinement

Process:

# Inject entire section with all components
wds figma inject-section login-form --file abc123 --include-children

Advantages:

• Complete context
• Layout refinement
• Holistic design decisions

---

Strategy 4: Iterative Refinement

When to use: Multiple refinement cycles needed

Process:

# Iteration 1: Inject basic components
wds figma inject btn-login-submit --file abc123

# Designer refines in Figma

# Read back refined version
wds figma read btn-login-submit --file abc123 --update-design-system

# Iteration 2: Re-inject with design system updates
wds figma inject btn-login-submit --file abc123 --version 2

# Continue until satisfied

Advantages:

• Incremental improvement
• Design system grows with each iteration
• Reduced rework

---

Object ID Mapping

Preservation Strategy

In HTML Prototype:

<button data-object-id="btn-login-submit" class="btn-primary">
  Log In
</button>

In Figma (after injection):

Layer name: "btn-login-submit"
Description: "Object ID: btn-login-submit"

In Design System:

# D-Design-System/components/button.md
Button Component [btn-001]

Object ID Mapping:
- btn-login-submit → Login page submit button
- btn-signup-cta → Signup page CTA button

---

Traceability

Benefits:

• Track component from spec → prototype → Figma → design system
• Identify which Figma components map to which code elements
• Update specific components without affecting others
• Maintain consistency across iterations

Workflow:

Specification: "Login button" (conceptual)
    ↓
Prototype: data-object-id="btn-login-submit" (code)
    ↓
Figma: Layer "btn-login-submit" (design)
    ↓
Design System: Button.primary [btn-001] (documentation)
    ↓
Re-rendered Prototype: class="btn-primary" (enhanced code)

---

Design Token Extraction

Automatic Token Detection

MCP Server analyzes:

• Colors used in component
• Spacing/padding values
• Typography styles
• Border radius
• Shadows/effects

Example extraction:

From Figma component:

Background: #2563eb
Text: #ffffff
Padding: 12px 16px
Border-radius: 8px
Font: Inter, 16px, 600

To Design Tokens:

colors:
  primary:
    600: "#2563eb"
  neutral:
    50: "#ffffff"

spacing:
  md: 12px
  lg: 16px

radius:
  md: 8px

typography:
  button:
    font-family: "Inter"
    font-size: 16px
    font-weight: 600

---

Token Mapping

MCP Server can:

• Detect similar colors and suggest token names
• Identify spacing patterns
• Recognize typography scales
• Propose token structure

Agent dialogue:

I've analyzed the refined button component and detected these values:

Colors:
- Background: #2563eb → Suggest: primary.600
- Text: #ffffff → Suggest: neutral.50

Spacing:
- Padding horizontal: 16px → Suggest: spacing.lg
- Padding vertical: 12px → Suggest: spacing.md

Would you like to:
[A] Accept all suggestions
[C] Customize token names
[R] Review each token

Choice:

---

Error Handling

Common Issues

Issue: Component not found in prototype

Error: Component with Object ID "btn-login-submit" not found in prototype

Solution:
- Verify Object ID exists in HTML
- Check data-object-id attribute
- Ensure prototype file is current

Issue: Figma file access denied

Error: Cannot access Figma file abc123

Solution:
- Verify Figma access token
- Check file permissions
- Ensure file ID is correct

Issue: Component structure too complex

Warning: Component has deeply nested structure (8 levels)
This may not convert cleanly to Figma

Suggestion:
- Simplify HTML structure
- Extract sub-components separately
- Use flatter hierarchy

---

Conflict Resolution

Scenario: Component exists in both prototype and Figma

Options:

Component btn-login-submit already exists in Figma.

[O] Overwrite with new version
[M] Merge changes
[V] Create new version
[S] Skip this component

Choice:

Merge strategy:

• Preserve Figma refinements
• Apply new structural changes
• Prompt for conflicts

---

Best Practices

DO ✅

1. Use Object IDs consistently

<!-- Good: Clear, consistent Object IDs -->
<button data-object-id="btn-login-submit">
<input data-object-id="input-email">
<a data-object-id="link-forgot-password">

2. Extract components incrementally

# Start with critical components
wds figma inject btn-login-submit --file abc123

# Then expand to related components
wds figma inject input-email --file abc123

3. Document extraction decisions

# extraction-log.md

## 2026-01-08: Login Page Components

Extracted to Figma:
- btn-login-submit: Needs brand color refinement
- input-email: Needs focus state design
- input-password: Needs show/hide icon

Skipped:
- link-terms: Standard link, no refinement needed

4. Sync regularly

# After designer completes refinement
wds figma read btn-login-submit --file abc123 --update-design-system

# Re-render to verify
wds prototype render login-page --with-design-system

---

DON'T ❌

1. Don't inject entire pages

# Avoid: Too broad, loses precision
wds figma inject-page login --file abc123

# Better: Specific components
wds figma inject btn-login-submit --file abc123

2. Don't skip Object ID mapping

<!-- Avoid: No traceability -->
<button class="btn-primary">

<!-- Better: Clear Object ID -->
<button data-object-id="btn-login-submit" class="btn-primary">

3. Don't forget to read back

# Incomplete workflow
wds figma inject btn-login-submit --file abc123
# Designer refines...
# ❌ Never read back refined version

# Complete workflow
wds figma inject btn-login-submit --file abc123
# Designer refines...
wds figma read btn-login-submit --file abc123 ✅

---

Advanced Features

Variant Detection

MCP Server can detect component variants:

Analyzing button components in Figma...

Found 3 button variants:
- btn-login-submit (primary variant)
- btn-cancel (secondary variant)
- btn-delete (danger variant)

Suggest creating Button component with variants?
[Y/N]:

---

State Extraction

MCP Server extracts component states:

Reading btn-login-submit from Figma...

States detected:
- Default: #2563eb background
- Hover: #1d4ed8 background (darker)
- Active: #1e40af background (darkest)
- Disabled: #9ca3af background (gray)

Add all states to design system?
[Y/N]:

---

Responsive Constraints

MCP Server preserves responsive behavior:

Component has responsive constraints:
- Width: Fill container
- Height: Hug contents
- Min width: 120px
- Max width: 400px

Apply constraints in re-rendered prototype?
[Y/N]:

---

Integration with Existing Figma Workflow

Compatibility

Works with existing Figma → WDS workflow:

Workflow A (Existing): Designer creates in Figma → MCP reads → WDS spec Workflow B (New): Prototype → MCP injects → Figma → MCP reads → WDS spec

Both workflows use same MCP server, same token extraction, same design system updates.

---

Unified Design System

All paths lead to design system:

Path 1: Manual Figma design → MCP → Design System
Path 2: Prototype → MCP → Figma → MCP → Design System
Path 3: Specification → Prototype → Design System (no Figma)

Result: Single source of truth in Design System

---

Performance Considerations

Batch Processing

Efficient for multiple components:

# Sequential (slower)
wds figma inject btn-1 --file abc123
wds figma inject btn-2 --file abc123
wds figma inject btn-3 --file abc123

# Batch (faster)
wds figma batch inject --list buttons.txt --file abc123

Performance:

• Sequential: ~5 seconds per component
• Batch: ~2 seconds per component (parallel processing)

---

Caching

MCP Server caches:

• Figma file structure
• Component definitions
• Design tokens
• Object ID mappings

Benefits:

• Faster subsequent operations
• Reduced API calls
• Offline capability (limited)

---

Security

API Token Management

Best practices:

# Never commit tokens to git
echo "FIGMA_ACCESS_TOKEN=*" >> .gitignore

# Use environment variables
export FIGMA_ACCESS_TOKEN="token"

# Or use secure credential storage
wds figma set-token --secure

---

Access Control

Figma file permissions:

• MCP server requires edit access to inject components
• Read-only access sufficient for reading refined components
• Consider separate files for WDS injection vs production design

---

Troubleshooting

Debug Mode

# Enable verbose logging
wds figma inject btn-login-submit --file abc123 --debug

# Output shows:
# - HTML parsing steps
# - Figma API calls
# - Conversion process
# - Injection details
# - Error stack traces

---

Validation

# Validate before injection
wds figma validate btn-login-submit

# Checks:
# - Object ID exists
# - HTML structure valid
# - CSS parseable
# - Figma file accessible

---

Summary

MCP Server integration enables:

✅ Precision: Inject specific components, not entire pages
✅ Automation: Automated Object ID mapping and token extraction
✅ Bidirectional: Prototype → Figma → Design System → Prototype
✅ Traceability: Maintain Object ID connections throughout
✅ Efficiency: Batch operations and caching
✅ Integration: Works with existing Figma workflows

Result: Seamless, precise component refinement workflow that maintains traceability and enables iterative design improvement.

---

This MCP server integration is the key to making the prototype-to-Figma workflow practical and efficient for production use.