whiteport-design-studio 0.1.0

package/src/workflows/5-design-system/figma-integration/reference/mcp-server-integration.md

@@ -0,0 +1,922 @@
+# 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:**
+```bash
+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:**
+```bash
+# 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-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:**
+```bash
+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:**
+```bash
+# Inject entire login form section
+wds figma inject-section login-form --file abc123 --include-children
+```
+
+---
+
+### Read Refined Component from Figma
+
+**Command:**
+```bash
+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:**
+```bash
+# 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:**
+```bash
+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:**
+```bash
+wds figma batch inject --list components-to-refine.txt --file abc123
+```
+
+---
+
+## Workflow Integration
+
+### Phase 4D: After Prototype Creation
+
+**Agent workflow:**
+
+```markdown
+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:**
+
+```markdown
+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**
+```bash
+npm install -g @wds/figma-mcp-server
+```
+
+**2. Configure Figma API Access**
+```bash
+# 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**
+```bash
+wds figma init
+```
+
+**4. Test Connection**
+```bash
+wds figma test-connection
+```
+
+---
+
+### Configuration File
+
+**Location:** `.wds/figma-mcp-config.yaml`
+
+```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-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-Scenarios/`
+
+---
+
+## Component Selection Strategies
+
+### Strategy 1: Individual Components
+
+**When to use:** Specific components need refinement
+
+**Process:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```html
+<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:**
+```yaml
+# 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:**
+```yaml
+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**
+```html
+<!-- 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**
+```bash
+# 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**
+```markdown
+# 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**
+```bash
+# 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**
+```bash
+# 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**
+```html
+<!-- 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**
+```bash
+# 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:**
+
+```bash
+# 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:**
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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.**