Figma integration

.eslintignore

@@ -0,0 +1,2 @@
+# Figma MCP Server - external project with different config
+figma-mcp-server/

eslint.config.mjs

@@ -22,6 +22,8 @@ export default [
       'build/**',
       // Website uses ESM/Astro - separate linting ecosystem
       'website/**',
+      // Figma MCP Server - external project with different config
+      'figma-mcp-server/**',
       // Gitignored patterns
       'z*/**', // z-samples, z1, z2, etc.
       '.claude/**',

src/modules/wds/README.md

@@ -1,10 +1,45 @@
-# Whiteport Design Studio (WDS) Module
+# Whiteport Design Studio (WDS) 🎨
 
-**Design-focused methodology for UX/UI product development**
+**Strategic design methodology for creating products users love**
 
-## Overview
+---
 
-Whiteport Design Studio provides a complete design workflow from product exploration through detailed component specifications. WDS creates the design artifacts that feed into development modules like BMad Method (BMM).
+## ⚠️ Installation Notice
+
+**The automated installer is currently not working.** You'll need to manually sideload the WDS agents.
+
+### Quick Sideload Instructions:
+
+1. **Copy agent files** from `src/modules/wds/agents/` to your IDE's agent configuration folder
+2. **Configure agent paths** in your IDE settings
+3. **Verify agents** appear in your IDE's agent list
+
+📖 **Detailed installation guide:** [docs/how-to/installation/install-bmad.md](../../docs/how-to/installation/install-bmad.md)
+
+---
+
+## What You Can Accomplish with WDS
+
+As a designer using WDS, you'll be able to:
+
+🎯 **Create strategic designs** - Connect every design decision to business goals and user psychology  
+📋 **Produce complete specifications** - Generate developer-ready page specs with all details defined  
+✨ **Explore with AI image generation** - Use NanoBanana/Eira to generate design concepts and establish visual identity  
+🎨 **Design with Figma** - Open your prototype in Figma, refine the design, export it back to update the design system and generate new code  
+🤖 **Leverage AI agents** - Work with Saga, Idunn, and Freya to accelerate your workflow  
+📦 **Deliver with confidence** - Hand off complete, tested prototypes with clear documentation  
+
+### What You Need to Learn
+
+To get the most out of WDS, you'll need to understand:
+
+1. **The WDS workflow** - How phases connect and when to use each one
+2. **Agent collaboration** - Working with Saga, Idunn, and Freya to accomplish tasks
+3. **Tool integration** - Using Figma MCP, NanoBanana, and other design tools
+
+<EFBFBD> **Start learning:** [docs/learn-wds/](docs/learn-wds/) - Interactive courses and tutorials
+
+---
 
 ## Module Structure
 
@@ -30,27 +65,70 @@ wds/
 └── README.md                   # This file (only README in module)
 ```
 
-## Output Folder Structure
+## 📁 Output Structure
 
-WDS creates an alphabetized folder structure in the user's `docs/` folder:
+WDS creates a clean, alphabetized folder structure in your project's `docs/` folder:
 
-| Folder             | Phase | Purpose                            |
+| Folder             | Phase | Purpose                                      | Timing              |
-| ------------------ | ----- | ---------------------------------- |
+| ------------------ | ----- | -------------------------------------------- | ------------------- |
-| `A-Product-Brief/` | 1     | Strategic foundation & vision      |
+| `A-Product-Brief/` | 1     | Strategic foundation & vision                | Start here          |
-| `B-Trigger-Map/`   | 2     | Business goals, personas, drivers  |
+| `B-Trigger-Map/`   | 2     | User psychology & business goals             | After Phase 1       |
-| `C-Scenarios/`     | 4     | Visual specifications & sketches   |
+| `C-Scenarios/`     | 4     | UX specifications (HOW it works)             | After Phase 2       |
-| `D-PRD/`           | 3     | Product requirements documentation |
+| `D-Design-System/` | 5     | Visual identity & components (HOW it looks)  | **Anytime** 🎨      |
-| `D-Design-System/` | 5     | Component library & design tokens  |
+| `D-PRD/`           | 3     | Technical requirements (optional)            | Before development  |
-| `E-UI-Roadmap/`    | 6     | Development integration bridge     |
+| `E-UI-Roadmap/`    | 6     | Development handoff                          | After Phase 4       |
 
-## Phases
+## 🎯 Design Phases
 
-1. **Product Exploration** → `A-Product-Brief/`
+### Core Workflow
-2. **User Research** → `B-Trigger-Map/`
+
-3. **Requirements** → `D-PRD/`
+**Phase 1: Product Exploration** → `A-Product-Brief/`  
-4. **Conceptual Design** → `C-Scenarios/` (with optional Figma visual refinement)
+Define vision, positioning, and success criteria
-5. **Component Design** → `D-Design-System/` (grows organically via Figma integration)
+
-6. **Dev Integration** → `E-UI-Roadmap/`
+**Phase 2: User Research** → `B-Trigger-Map/`  
+Connect business goals to user psychology and triggers
+
+**Phase 4: UX Design** → `C-Scenarios/`  
+**HOW it works** - Functionality, interactions, content structure
+
+**Phase 5: Visual Design** → `D-Design-System/`  
+**HOW it looks** - Tie UX to brand, create visual system  
+⚡ **Can start anytime** - Brand identity is independent of product!
+
+### Optional Phases
+
+**Phase 3: Requirements** → `D-PRD/` (for technical products)  
+**Phase 6: Dev Integration** → `E-UI-Roadmap/` (handoff to development)
+
+---
+
+## 💡 Key Concepts
+
+### UX vs Visual Design
+
+```
+Phase 4 (UX Design)
+├─ Defines HOW it works
+├─ Functionality & interactions
+├─ Content structure & hierarchy
+└─ Question: "What does this do?"
+
+Phase 5 (Visual Design)
+├─ Defines HOW it looks and feels
+├─ Brand expression & visual language
+├─ Design tokens & system
+└─ Question: "How does this feel like our brand?"
+```
+
+### Brand Independence
+
+**Visual design is NOT tied to product timing!**
+
+- ✅ Before product work (brand-first approach)
+- ✅ Parallel to strategy (simultaneous development)
+- ✅ After strategy (informed by insights)
+
+**Output location:** `D-Design-System/01-Visual-Design/`
 
 ## Agents - The Norse Pantheon 🏔️
 
@@ -60,31 +138,75 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder:
 | **Idunn the PM**        | `idunn-pm.agent.yaml`     | Product Manager            | Goddess of renewal & youth          |
 | **Freya the Designer** | `freya-ux.agent.yaml`    | UX/UI Designer             | Goddess of beauty, magic & strategy |
 
-## Conventions
+## 🛠️ Tools & Integration
 
-- **One README rule:** Only this README.md; all other docs use `xxx-guide.md` naming
+### Visual Design Tools
-- **Alphabetized output:** A-B-C-D-E folder prefix in user projects
-- **Design focus:** No development artifacts (handled by BMM)
-- **Phase-selectable:** Users choose phases based on project scale
 
-## Quick Start
+- **Figma MCP** - Automated bidirectional sync with Object IDs
+- **NanoBanana/Eira** - AI-powered image generation for brand exploration
+- **html.to.design** - Import HTML prototypes into Figma
+
+### Workflow Tools
+
+- **Excalidraw** - Sketch analysis and wireframing
+- **Git** - Version control and collaboration
+- **Cursor/Windsurf** - AI-powered IDE integration
+
+📖 **Full tools guide:** [docs/tools/wds-tools-guide.md](docs/tools/wds-tools-guide.md)
+
+---
+
+## 📋 Conventions
+
+- **One README rule** - Only this README.md; all other docs use `xxx-guide.md` naming
+- **Alphabetized output** - A-B-C-D-E folder prefix for clean organization
+- **Design focus** - No development artifacts (handled by BMM)
+- **Phase-selectable** - Choose phases based on project needs
+- **Tool-agnostic** - Works with any design/development tools
+
+## 🚀 Getting Started
+
+### 1. Sideload Agents (Manual Installation)
+
+Since the installer isn't working, manually copy agents:
+
+```bash
+# Copy agent files to your IDE's agent folder
+cp src/modules/wds/agents/*.yaml <your-ide-agent-folder>/
+```
+
+### 2. Activate an Agent
+
+In your IDE, activate one of the WDS agents:
+- **Saga** - Business & Product Analyst
+- **Idunn** - Product Manager  
+- **Freya** - UX/UI Designer
+
+### 3. Initialize Workflow
 
 ```
-# After installing BMad with WDS module
-npx bmad-method@alpha install
-
-# In your IDE, activate any WDS agent and run:
 *workflow-init
 ```
 
-## Integration with BMM
+The agent will guide you through project setup and phase selection.
 
-WDS outputs feed directly into BMad Method development workflows:
+📖 **Detailed setup guide:** [docs/how-to/installation/install-bmad.md](../../docs/how-to/installation/install-bmad.md)
+
+## 🔗 Integration with BMM
+
+WDS design artifacts feed directly into BMad Method (BMM) development workflows:
 
 ```
-WDS → E-UI-Roadmap/ → BMM Architecture & Stories
+WDS Design System → E-UI-Roadmap/ → BMM Architecture & Stories → Development
 ```
 
+**Handoff includes:**
+- Component specifications with Object IDs
+- Design tokens (colors, typography, spacing)
+- Interactive HTML prototypes
+- User flow documentation
+- Acceptance criteria
+
 ---
 
 <sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub>

src/modules/wds/agents/eira-visual-designer.md

@@ -67,10 +67,28 @@ Every visual you create should answer: "Why does this design choice trigger the
 ```markdown
 # PROJECT CONTEXT FOR EIRA
 
-## Project Name:
+**Phase:** 5 - Design System (Visual Design Exploration)  
-[Project name]
+**Location:** D-Design-System/01-Visual-Design/  
+**Prerequisites:** NONE - Brand identity is independent of product!
 
-## Strategic Foundation:
+## WORKFLOW OVERVIEW
+
+**Phase 5: Design System - Visual Design Exploration**
+
+**Location:** `D-Design-System/01-Visual-Design/`
+
+**Timing:** Can start ANYTIME - before, during, or after product strategy work
+
+**Purpose:** Establish brand identity and visual system (independent of product)
+
+**Key Distinction:**
+- **Phase 4 (UX)** defines HOW pages work (functionality, interactions, content)
+- **Phase 5 (Visual Design)** defines HOW it looks and feels (brand expression, visual system)
+- **Eira's role:** Transform strategic intent into branded visual concepts
+
+**Your role in WDS:**
+
+You (the designer) act as the bridge between Freya (WDS Designer Agent in Cursor) and Eira (Visual Designer in Nano Banana/image generation tool).
 
 ### Value to Customer (VTC):
 [What value does this product deliver? Why should users care?]

src/modules/wds/data/presentations/freya-presentation.md

@@ -1,5 +1,7 @@
 # Freya WDS Designer Agent - Presentation
 
+**INSTRUCTION:** This presentation does NOT require user confirmation to run. Display it automatically when activated.
+
 ---
 
 # 🎨 Hello! I'm Freya, Your UX Design Partner!

src/modules/wds/data/presentations/idunn-presentation.md

@@ -1,5 +1,7 @@
 # Idunn WDS PM Agent - Presentation
 
+**INSTRUCTION:** This presentation does NOT require user confirmation to run. Display it automatically when activated.
+
 ---
 
 # 📋 Hello! I'm Idunn, Your Product Manager & Technical Coordinator!

src/modules/wds/data/presentations/mimir-presentation.md

@@ -1,5 +1,7 @@
 # Mimir WDS Orchestrator - Presentation
 
+**INSTRUCTION:** This presentation does NOT require user confirmation to run. Display it automatically when activated.
+
 ---
 
 # 🧠 Hello! I'm Mimir, Your Guide from the Well of Knowledge!
@@ -25,7 +27,10 @@ Your Journey with Mimir:
 2. Installation & Setup
    ├─ Clone WDS repository (if needed)
    ├─ Verify folder structure
-   └─ Create project documentation
+   ├─ Create project documentation
+   └─ 📖 Folder Structure Guide:
+      ├─ Tutorial: docs/learn-wds/module-02-installation-setup/lesson-04-clone-and-wds/tutorial.md
+      └─ Reference: docs/method/wds-method-guide.md (Folder Structure section)
 
 3. Project Analysis
    ├─ Understand your project

src/modules/wds/data/presentations/saga-presentation.md

@@ -1,5 +1,7 @@
 # Saga WDS Analyst Agent - Presentation
 
+**INSTRUCTION:** This presentation does NOT require user confirmation to run. Display it automatically when activated.
+
 ---
 
 # 📚 Hello! I'm Saga, Your Strategic Business Analyst!

src/modules/wds/docs/examples/wds-v6-conversion/session-logs/2026-01-04-eira-visual-design-integration.md

@@ -11,9 +11,11 @@
 
 Designed complete integration of **Eira** (visual design agent) into WDS workflow. Eira enables AI-powered visual design exploration using image generation models (Nano Banana, DALL-E, Midjourney, etc.) while maintaining strategic alignment with BMad Method principles.
 
-**Key Innovation:** Phase 2.5 "Visual Design Brief" - a creative exploration phase between strategy (Phase 2) and detailed scenarios (Phase 4) where wild visual concepts are generated before locking into detailed specs.
+**Key Innovation:** Phase 5 "Visual Design Exploration" (01-Visual-Design/) - a creative exploration phase that happens AFTER strategy (Phase 1 & 2) but BEFORE detailed scenarios (Phase 4), where wild visual concepts are generated before locking into detailed specs.
 
-**Core Principle:** Strategy → Creative Exploration → Detailed Execution
+**Location:** `D-Design-System/01-Visual-Design/`
+
+**Core Principle:** Strategy (Phase 1 & 2) → Visual Exploration (Phase 5) → Detailed Execution (Phase 4)
 
 ---
 
@@ -48,37 +50,64 @@ Phase 2: Trigger Mapping
 ├─ Psychological triggers
 └─ User context (informs device priorities)
 
-Phase 2.5: Visual Design Brief ← NEW!
+Phase 5: Design System - Visual Design Exploration (BEFORE Phase 4)
+├─ Location: D-Design-System/01-Visual-Design/
 ├─ Strategic document (tool-agnostic)
 ├─ Content concept generation
 ├─ Visual exploration (wild & creative)
 ├─ Direction selection
 └─ Design token extraction
 
-Phase 3: PRD/Platform
+Phase 3: PRD/Platform (Optional)
 ├─ Technical foundation
-└─ Device priorities (informed by Phase 2.5)
+└─ Device priorities (informed by Phase 5 visual direction)
 
 Phase 4: UX Design (Scenarios)
 ├─ Detailed conceptual specs
-├─ High-fidelity mockups (using approved direction)
+├─ High-fidelity mockups (using approved direction from Phase 5)
 ├─ HTML prototypes
 └─ Design system evolution
+
+Phase 5: Design System - Production Assets (DURING/AFTER Phase 4)
+├─ Location: D-Design-System/02-Assets/
+├─ Component extraction
+├─ Final logos and assets
+└─ Design system documentation
 ```
 
 ---
 
-## Phase 2.5: Visual Design Brief (Detailed)
+## Phase 5: Visual Design Exploration (Detailed)
+
+**Location:** `D-Design-System/01-Visual-Design/`
 
 ### Purpose
 
+**Tie UX to Brand and create a visual system.** This phase establishes the visual language that will express your brand's personality across all user experiences.
+
+**Key Distinction:**
+- **Phase 4 (UX)** = How it works (functionality, interactions, content)
+- **Phase 5 (Visual Design)** = How it looks and feels (brand expression, visual system)
+
 **Strategic document** that defines boundaries and direction for visual exploration. Completely **tool-agnostic** - focuses on WHAT to explore, not HOW to generate.
 
+**Timing:** Can happen ANYTIME - visual identity/brand is independent of product strategy. Common scenarios:
+- **Before product:** Establish brand first, build products around it
+- **Parallel:** Develop brand while defining product strategy  
+- **After strategy:** Use strategic insights to inform visual direction
+
 ### Content Structure
 
+**Output Location:** `D-Design-System/01-Visual-Design/visual-design-brief.md`
+
 ```markdown
 # Visual Design Brief: [Project Name]
 
+**Phase:** 5 - Design System (Visual Design Exploration)  
+**Location:** D-Design-System/01-Visual-Design/  
+**Created After:** Phase 1 (Product Brief) and Phase 2 (Trigger Map)  
+**Used In:** Phase 4 (UX Design) for scenario creation
+
 ## Strategic Foundation
 - Value to Customer (VTC)
 - Target Demographics
@@ -109,6 +138,12 @@ For each key page (homepage, features, pricing, etc.):
 ## Success Criteria
 - Evaluation questions
 - Strategic alignment checks
+
+## Output Organization
+- Mood boards → 01-Visual-Design/mood-boards/
+- Design concepts → 01-Visual-Design/design-concepts/
+- Color exploration → 01-Visual-Design/color-exploration/
+- Typography tests → 01-Visual-Design/typography-tests/
 ```
 
 ### Visual Prosperity Standards

src/modules/wds/docs/method/phase-5-design-system-guide.md

@@ -109,9 +109,18 @@ Notice pattern across pages  →    Extract as reusable component
 
 ### Visual Design Exploration (01-Visual-Design/)
 
-**Early Design Phase - Before Scenarios:**
+**Independent Design Phase - Can Start Anytime:**
 
-Before diving into scenario-specific design, establish your visual direction:
+**Key Insight:** Brand identity and visual design are NOT tied to the product! You can establish your visual identity at any time - before, during, or after product strategy work.
+
+**Purpose:** Establish the visual language that will tie UX to Brand. This is where you define how your brand's personality will be expressed visually across all touchpoints.
+
+**Timing Options:**
+- **Before product work:** Establish brand identity first, then build products around it
+- **Parallel to strategy:** Develop visual identity while defining product strategy
+- **After strategy:** Use strategic insights to inform visual direction
+
+Before diving into scenario-specific design (Phase 4), establish your visual direction:
 
 **Mood Boards:**
 - Collect visual inspiration
@@ -138,10 +147,11 @@ Before diving into scenario-specific design, establish your visual direction:
 - Document font usage guidelines
 
 **When to Use:**
-- At project start (before Phase 4 scenarios)
+- **AFTER Phase 1 & 2** (Product Brief and Trigger Map must be complete first!)
-- When establishing brand identity
+- When establishing brand identity (with strategic context)
-- When exploring multiple visual directions
+- When exploring multiple visual directions (informed by user psychology)
 - Before committing to design tokens
+- Before Phase 4 scenarios (but after strategic foundation)
 
 **Output Location:** `D-Design-System/01-Visual-Design/`
 

src/modules/wds/docs/tools/figma-mcp.md

@@ -305,6 +305,131 @@ echo "FIGMA_ACCESS_TOKEN=token" > .env
 
 ---
 
+## 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`
+
+```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**
+
+1. Open Figma Desktop with your paid account
+2. The official Figma MCP server runs automatically on port 3845
+3. Open your design file
+4. Select the node/frame you want to extract
+
+**3. Windsurf Configuration**
+
+1. Open Windsurf Settings: `Ctrl+,` (or `Cmd+,` on Mac)
+2. Navigate to: **Tools → Windsurf Settings → MCP Servers**
+3. Click the **refresh button** after modifying `mcp_config.json`
+4. 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:**
+
+1. **In Figma Desktop**: Select the color palette frame
+2. **In Windsurf**: Call the MCP tool:
+
+```
+mcp1_get_design_context(
+  clientLanguages: "markdown",
+  clientFrameworks: "unknown",
+  nodeId: "",  // Empty for currently selected node
+  dirForAssetWrites: "path/to/assets"
+)
+```
+
+3. **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
+
+1. **Automated Design Token Extraction**: No manual copying of color codes, spacing values, etc.
+2. **Single Source of Truth**: Design definitions come directly from Figma
+3. **Version Control**: Changes in Figma can be re-extracted and documented
+4. **AI Agent Integration**: Freya can reference actual design system values
+5. **Reduced Human Error**: Eliminates transcription mistakes
+
+---
+
 ## Resources
 
 **Documentation:**

src/modules/wds/docs/tools/nanobanana.md

@@ -51,10 +51,12 @@ NanoBanana has two integration workflows in WDS:
 
 #### **Workflow A: Early Design Exploration**
 
+**Key Insight:** Brand identity is INDEPENDENT of product! You can establish visual identity anytime - before, during, or after product strategy.
+
 ```
-Phase 5: Visual Design Exploration
+Phase 5: Visual Design Exploration (can happen ANYTIME)
     ↓
-NanoBanana (create assets/inspiration)
+NanoBanana (create brand assets/visual identity)
     ↓
 Save to D-Design-System/01-Visual-Design/
     ↓
@@ -204,11 +206,11 @@ Create/update prototype with refined design
 ### Use NanoBanana for:
 
 **Early Design Exploration:**
-- Custom graphics and icons
+- **ANYTIME** - Brand identity is independent of product strategy!
-- Design inspiration
+- When establishing brand identity (can be before, during, or after product work)
-- Exploring visual concepts
+- When exploring multiple visual directions
-- Creating placeholder assets
+- Before committing to design tokens
-- Brand identity exploration
+- Can happen before Phase 1, parallel to strategy work, or after Phase 4
 
 **Sketch Envisioning (Alternative to Figma):**
 - Converting sketches to visual designs quickly

src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md

@@ -1,130 +1,113 @@
-# WDS Prototype-to-Figma Integration - Summary
+# Figma Integration - Summary
 
-**Date Added:** January 8, 2026  
+**Last Updated:** January 9, 2026  
 **Version:** WDS v6  
-**Status:** Ready for Public Release
+**Status:** Active Development
 
 ---
 
-## What Was Added
+## Overview
 
-This integration completes the WDS design workflow by adding the missing dimension: **visual design creation and refinement**.
+This integration enables bidirectional workflow between code and Figma for design system development and visual refinement.
 
-### New Workflow: Iterative Design Refinement
+### Bidirectional Workflow
 
 ```
-Sketch → Spec → Prototype → Figma (if needed) → Design System → Re-render → Iterate
+Code ⇄ Figma
 ```
 
-**Key Innovation:** Code prototypes serve as functional starting points. When design system is incomplete, extract to Figma for visual refinement, then feed improvements back to design system and re-render.
+**Two Main Workflows:**
+
+1. **Code to Figma (C2F):** Send code implementations to Figma for visual documentation and refinement
+2. **Figma to Code (F2C):** Import design specifications from Figma to generate or update code
+
+**Key Innovation:** Specification-driven approach ensures design-code parity through shared OBJECT IDs, enabling traceability and consistency across both directions.
 
 ---
 
-## New Documentation Files
+## Workshop Structure
 
-### 1. Prototype-to-Figma Workflow
+### Code to Figma (C2F) Workshop
-**File:** `prototype-to-figma-workflow.md`
+**Location:** `code-to-figma/`
 
-**Purpose:** Complete workflow for extracting HTML prototypes to Figma for visual refinement
+**Purpose:** Send code implementations to Figma for design review, documentation, and visual iteration
 
-**Covers:**
+**Workflow Steps:**
-- When and why to extract prototypes
+1. Connection Check - Verify html.to.design MCP server
-- Step-by-step extraction process using html.to.design
+2. Identify Type - Determine export scenario (prototype page, design system component, or frontend view)
-- Figma refinement techniques
+3. Prepare Specifications - Find or create OBJECT IDs for proper Figma layer naming
-- Design system update process
+4. Generate & Validate - Create Figma-compatible HTML with validation
-- Re-rendering with enhanced design system
+5. Send to Figma - Execute export and verify success
-- Iteration strategies
-
-**Key Sections:**
-- Phase 1: Identify need for refinement
-- Phase 2: Extract to Figma
-- Phase 3: Refine design
-- Phase 4: Extract design system updates
-- Phase 5: Re-render prototype
-- Phase 6: Iterate or complete
-
----
-
-### 2. When to Extract Decision Guide
-**File:** `when-to-extract-decision-guide.md`
-
-**Purpose:** Help designers make informed decisions about when to extract prototypes to Figma
-
-**Covers:**
-- Decision tree and framework
-- Quick assessment checklist
-- Scenarios and examples
-- Design system maturity levels
-- Cost-benefit analysis
-- Quality thresholds
-- Practical examples
 
 **Key Features:**
-- Clear decision criteria
+- Specification-driven OBJECT ID naming
-- Red flags to avoid
+- Three export scenarios with specific ID patterns
-- Decision matrix
+- Automated validation before export
-- Time investment analysis
+- Reverse engineering for missing specifications
-- Priority guidance
 
 ---
 
-### 3. Tools Reference
+### Figma to Code (F2C) Workshop
-**File:** `tools-reference.md`
+**Location:** `figma-to-code/`
 
-**Purpose:** Quick reference for design tools used in WDS workflows
+**Status:** Coming Soon
 
-**Covers:**
+**Purpose:** Import design specifications from Figma to generate or update code implementations
-- **html.to.design:** HTML → Figma conversion
-- **NanoBanana:** Spec → Code generation (optional)
-- **Area Tag System:** Region mapping for image prototypes
-- **Dev Mode Component:** Object ID extraction
 
-**Key Sections:**
+**Planned Workflow:**
-- Tool features and capabilities
+1. Connection Check - Verify Figma Desktop MCP server
-- How to use each tool
+2. Select Figma Node - Identify what to import
-- Best practices
+3. Extract Design Specs - Get colors, spacing, typography, layout
-- Limitations
+4. Generate/Update Code - Create or update components
-- Integration workflows
+5. Verify Implementation - Compare code output to Figma design
-- Troubleshooting
 
 ---
 
-## Updated Files
+## Reference Documentation
 
-### 1. Phase 4D Prototype Workflow
+**Location:** `reference/`
-**File:** `workflows/4-ux-design/substeps/4d-prototype.md`
 
-**Changes:**
+Supporting documentation for Figma integration workflows:
-- Added visual quality assessment after prototype testing
+
-- Integrated Figma extraction option
+1. **`figma-designer-guide.md`** - Guide for designers creating components in Figma
-- References to new workflow documentation
+2. **`mcp-server-integration.md`** - MCP server setup and configuration
-- Decision points for refinement vs completion
+3. **`tools-reference.md`** - Reference for Figma MCP tools and parameters
+4. **`when-to-extract-decision-guide.md`** - Decision tree for when to use Figma integration
+5. **`figma-mcp-integration.md`** - Technical documentation about MCP integration
+6. **`prototype-to-figma-workflow.md`** - Iterative refinement workflow documentation
+
+---
+
+## Folder Structure
 
-**New Flow:**
 ```
-Prototype Complete → Visual Assessment → 
+figma-integration/
-  Option 1: Polished (continue)
+├── code-to-figma/              # C2F Workshop
-  Option 2: Needs refinement (extract to Figma)
+│   ├── workflow.md
-  Option 3: Minor tweaks (quick CSS fixes)
+│   └── steps/
+│       ├── step-01-connection-check.md
+│       ├── step-02-identify-export-type.md
+│       ├── step-03-prepare-specifications.md
+│       ├── step-04-generate-validate.md
+│       ├── step-05-execute-export.md
+│       └── [substeps folders]
+│
+├── figma-to-code/              # F2C Workshop (coming soon)
+│   └── README.md
+│
+├── reference/                  # Reference documentation
+│   ├── figma-designer-guide.md
+│   ├── mcp-server-integration.md
+│   ├── tools-reference.md
+│   ├── when-to-extract-decision-guide.md
+│   ├── figma-mcp-integration.md
+│   └── prototype-to-figma-workflow.md
+│
+└── INTEGRATION-SUMMARY.md      # This file
 ```
 
 ---
 
-### 2. Phase 5 Design System README
-**File:** `workflows/5-design-system/README.md`
-
-**Changes:**
-- Added Prototype → Figma → WDS workflow (Workflow B)
-- Updated Figma Integration section
-- Referenced new documentation files
-- Documented iterative refinement capability
-
-**New Workflows:**
-- Workflow A: Figma → WDS (existing)
-- Workflow B: Prototype → Figma → WDS (new)
-
----
-
 ## Core Concepts
 
 ### The Missing Dimension

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-connection-check.md

@@ -0,0 +1,118 @@
+# Step 1: Connection Check & Installation
+
+**Progress: Phase 1 of 6** - Next: Identify Export Scenario
+
+**Duration:** 5-10 minutes (if setup needed)
+
+---
+
+## YOUR TASK
+
+Verify html.to.design MCP server connection and guide user through setup if needed.
+
+---
+
+## GOAL
+
+Ensure the export tool is available before proceeding with the workflow.
+
+---
+
+## EXECUTION
+
+### Check MCP Tool Availability
+
+<action>
+Check if `mcp2_import-html` tool is accessible in current session.
+Tool should be from "html.to.design MCP server"
+</action>
+
+**Decision Point:**
+- ✅ Tool available → **Skip to Step 2**
+- ❌ Tool not available → **Continue with substeps**
+
+---
+
+## IF TOOL NOT AVAILABLE
+
+<output>⚠️ Code to Figma Setup Required
+
+The html.to.design MCP server is not currently connected. To send code to Figma, we need to set up the integration.
+
+This requires:
+1. Figma account with project access
+2. html.to.design plugin installed in Figma
+3. MCP server configured in your IDE
+
+Would you like me to guide you through the setup process?</output>
+
+<ask>Proceed with setup? [Yes/No]:</ask>
+
+**If Yes:** Execute substeps in order  
+**If No:** Stop workflow, suggest alternative
+
+---
+
+## SUBSTEPS (Execute if setup needed)
+
+**→ [Substep 1.1: Guide Plugin Installation](./step-01-substeps/substep-01-plugin-installation.md)**
+
+After all substeps complete, return here to verify connection.
+
+---
+
+## VERIFICATION
+
+Once setup complete (or if tool was already available):
+
+<action>
+Execute test export:
+```javascript
+mcp2_import-html({
+  name: "Connection Test",
+  html: "<div style='padding: 20px; background: #f0f0f0; border-radius: 8px; font-family: sans-serif;'>✅ Connection Test Successful</div>"
+})
+```
+</action>
+
+**Expected Response:**
+```json
+{
+  "node": {
+    "id": "X:XXX",
+    "name": "Connection Test by html.to.design...",
+    "type": "SECTION"
+  }
+}
+```
+
+<ask>Can you see the "Connection Test" layer in your Figma file? [Yes/No]:</ask>
+
+**If Yes:** ✅ Connection verified!  
+**If No:** Execute troubleshooting substeps
+
+---
+
+## NEXT STEP
+
+Once connection verified:
+
+**→ Proceed to [Step 2: Identify Export Scenario](./step-02-identify-scenario.md)**
+
+---
+
+## OUTPUT AT THIS POINT
+
+You now have:
+- ✅ html.to.design MCP server connected
+- ✅ Connection verified with test export
+
+Still need:
+- ⏸️ Export scenario identified
+- ⏸️ Specifications located/created
+- ⏸️ HTML generated and validated
+- ⏸️ Final export executed
+
+---
+
+*Step 1 complete - Ready to export*

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-01-plugin-installation.md

@@ -0,0 +1,37 @@
+# Substep 1.1: Guide Plugin Installation
+
+**Parent Step:** Connection Check & Installation
+
+---
+
+## YOUR TASK
+
+Provide step-by-step instructions for installing html.to.design plugin in Figma.
+
+---
+
+## EXECUTION
+
+<output>**Step 1: Install html.to.design Plugin**
+
+Please follow these steps to install the plugin:</output>
+
+<output>
+1. Open Figma (desktop app or web: figma.com)
+2. Click on your profile icon (top-right corner)
+3. Select "Community" from the menu
+4. In the search bar, type "html.to.design"
+5. Click on the "html.to.design" plugin result
+6. Click "Install" or "Try it out" button
+7. Plugin is now installed
+</output>
+
+<ask>Have you completed the plugin installation? [Yes/No]:</ask>
+
+**Wait for user confirmation before proceeding.**
+
+---
+
+## NEXT SUBSTEP
+
+**→ Proceed to [Substep 1.2: Activate Plugin](./substep-02-activate-plugin.md)**

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-02-activate-plugin.md

@@ -0,0 +1,37 @@
+# Substep 1.2: Activate Plugin
+
+**Parent Step:** Connection Check & Installation
+
+---
+
+## YOUR TASK
+
+Guide user to activate the html.to.design plugin in their Figma file.
+
+---
+
+## EXECUTION
+
+<output>**Step 2: Activate the Plugin**
+
+Now let's activate the plugin in your Figma file:</output>
+
+<output>
+1. Open any Figma file (or create a new one for testing)
+2. Right-click anywhere on the canvas
+3. Select "Plugins" → "html.to.design"
+   OR
+   Use the menu: Plugins → html.to.design
+4. The plugin panel should appear on the right side of your screen
+5. Keep the plugin panel open during the export process
+</output>
+
+<ask>Can you see the html.to.design plugin panel? [Yes/No]:</ask>
+
+**Wait for user confirmation before proceeding.**
+
+---
+
+## NEXT SUBSTEP
+
+**→ Proceed to [Substep 1.3: Verify MCP Configuration](./substep-03-verify-mcp.md)**

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-03-verify-mcp.md

@@ -0,0 +1,51 @@
+# Substep 1.3: Verify MCP Configuration
+
+**Parent Step:** Connection Check & Installation
+
+---
+
+## YOUR TASK
+
+Confirm that the html.to.design MCP server is configured in the IDE.
+
+---
+
+## EXECUTION
+
+<output>**Step 3: Verify MCP Server Configuration**
+
+The html.to.design MCP server should be configured in your IDE settings.</output>
+
+<ask>Please check:
+1. Open your IDE Settings/Preferences
+2. Navigate to the MCP Servers section
+3. Look for "html.to.design" in the server list
+
+Is the html.to.design MCP server listed and enabled? [Yes/No]:</ask>
+
+**Wait for user response.**
+
+---
+
+## IF YES
+
+<output>✅ MCP server is configured. Let's test the connection.</output>
+
+**→ Return to [Step 1: Connection Check](../step-01-connection-check.md#verification) to run test export**
+
+---
+
+## IF NO
+
+<output>⚠️ MCP Server Not Configured
+
+The html.to.design MCP server needs to be added to your IDE configuration.
+
+Please refer to your IDE's MCP server documentation for configuration steps. The server should connect to the html.to.design plugin running in Figma.
+
+Once configured, please confirm and we'll test the connection.</output>
+
+<ask>Have you configured the MCP server? [Yes/Retry/Need Help]:</ask>
+
+**If Yes:** Return to verification  
+**If Need Help:** Provide IDE-specific configuration guidance

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-02-identify-export-type.md

@@ -0,0 +1,161 @@
+# Step 2: Identify Code to Figma Type
+
+**Progress: Step 2 of 5** - Next: Prepare Specifications
+
+**Duration:** 2-3 minutes
+
+---
+
+## YOUR TASK
+
+Determine which type of code-to-Figma scenario applies to the current request.
+
+---
+
+## GOAL
+
+Match the user's request to one of three scenarios to ensure proper ID naming and structure.
+
+---
+
+## EXECUTION
+
+### Analyze User Request
+
+<action>
+Examine the user's request and extract:
+- Component/page name
+- Scope (full page vs. component vs. block)
+- Purpose (design system, prototype, visual adjustment)
+- States/variations mentioned
+</action>
+
+---
+
+### Determine Scenario Type
+
+<output>Based on your request, I need to determine the export type...</output>
+
+**Decision Tree:**
+
+```
+IF request mentions:
+  - Full page/screen
+  - Multiple sections (header, hero, footer)
+  - User flow or journey
+  - Page layout
+  → Scenario A: Prototype Page Export
+
+ELSE IF request mentions:
+  - Component states (hover, active, disabled)
+  - Design system documentation
+  - Reusable component
+  - Component library
+  → Scenario B: Design System Component
+
+ELSE IF request mentions:
+  - Visual adjustments
+  - Spacing/layout iteration
+  - Specific UI block
+  - Rapid prototyping
+  → Scenario C: Frontend View/Component Block
+
+ELSE:
+  → Ask user for clarification
+```
+
+---
+
+### Confirm with User
+
+<output>📋 I've identified this as:
+
+**Scenario {A/B/C}: {Scenario Name}**
+
+This means we'll export:
+- {Description of what will be exported}
+- ID naming pattern: {pattern}
+- Expected outcome: {outcome}
+
+Is this correct, or would you like to adjust the scope?</output>
+
+<ask>Proceed with this scenario? [Yes/Adjust/Cancel]:</ask>
+
+**Wait for user confirmation.**
+
+---
+
+## SCENARIO DETAILS
+
+### Scenario A: Prototype Page Export
+
+**When:** Full page/screen implementation ready for design review
+
+**ID Pattern:** `{page}-{section}-{element}`
+
+**Example IDs:**
+```
+start-page-header
+start-page-hero
+start-hero-headline
+start-hero-cta
+start-message-section
+```
+
+---
+
+### Scenario B: Design System Component
+
+**When:** Reusable component with states/variations needs documentation
+
+**ID Pattern:** `{component}-{variant}-{state}`
+
+**Example IDs:**
+```
+btn-cta-primary-default
+btn-cta-primary-hover
+btn-cta-primary-active
+btn-cta-primary-disabled
+```
+
+---
+
+### Scenario C: Frontend View/Component Block
+
+**When:** Specific UI block needs visual iteration or adjustment
+
+**ID Pattern:** `{component}-{element}-{descriptor}`
+
+**Example IDs:**
+```
+language-selector-button
+language-selector-icon
+language-selector-dropdown
+language-selector-item-en
+```
+
+---
+
+## NEXT STEP
+
+Once scenario confirmed:
+
+**→ Proceed to [Step 3: Prepare Specifications](./step-03-prepare-specifications.md)**
+
+---
+
+## OUTPUT AT THIS POINT
+
+You now have:
+- ✅ MCP connection verified
+- ✅ Export scenario identified
+- ✅ ID naming pattern determined
+
+Still need:
+- ⏸️ Specifications located/created
+- ⏸️ HTML generated and validated
+- ⏸️ Final export executed
+
+---
+
+*Step 2 complete - Export type identified*

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-prepare-specifications.md

@@ -0,0 +1,138 @@
+# Step 3: Prepare Specifications
+
+**Progress: Step 3 of 5** - Next: Generate & Validate
+
+**Duration:** 5-15 minutes (depending on whether specs exist)
+
+---
+
+## YOUR TASK
+
+Locate existing specifications with OBJECT IDs, or create them if they don't exist.
+
+---
+
+## GOAL
+
+Ensure all components have proper OBJECT IDs from specifications for consistent Figma layer naming.
+
+---
+
+## EXECUTION
+
+### Search for Specification Documents
+
+<action>
+Search for specification files that may contain OBJECT IDs:
+
+1. Search in `docs/C-Scenarios/` for scenario specifications
+2. Search in `docs/D-Design-System/` for component documentation
+3. Use grep_search to find files containing "OBJECT ID"
+4. Look for markdown files matching component/page name
+</action>
+
+---
+
+### Decision Point: Specifications Found?
+
+**If specifications exist with OBJECT IDs:**
+
+<output>✅ Found specification documents with OBJECT IDs:
+
+{list of files and IDs found}
+
+I'll use these OBJECT IDs for the export.</output>
+
+<action>
+Extract OBJECT IDs from specifications:
+- Read specification files
+- Extract all OBJECT ID field values
+- Map to components in code
+- Store mapping for HTML generation
+</action>
+
+**→ Skip to validation and proceed to Step 4**
+
+---
+
+**If NO specifications exist:**
+
+<output>📝 No specifications found for these components.
+
+To maintain design-code parity and proper naming in Figma, I recommend creating a specification document.
+
+I can:
+1. Analyze the code and reverse-engineer specifications
+2. Generate OBJECT IDs following project conventions
+3. Create a specification document for your review
+
+Would you like me to create specifications for these components?</output>
+
+<ask>Create specifications? [Yes/No]:</ask>
+
+**If Yes:** Execute substeps  
+**If No:** Auto-generate temporary IDs (with warning)
+
+---
+
+## SUBSTEPS (Execute if creating specifications)
+
+**→ [Substep 3.1: Analyze Code](./step-03-substeps/substep-01-analyze-code.md)**
+
+After all substeps complete, return here with generated OBJECT IDs.
+
+---
+
+## VALIDATION
+
+<action>
+Validate specification coverage:
+
+FOR EACH component in export scope:
+  IF component has OBJECT ID:
+    ✅ Mark as validated
+  ELSE:
+    ⚠️ Add to "missing specification" list
+
+Generate coverage report
+</action>
+
+<output>📋 Specification Coverage Report:
+
+✅ Components with OBJECT IDs: {count}
+  - {list}
+
+⚠️ Components missing OBJECT IDs: {count}
+  - {list}
+
+Coverage: {percentage}%</output>
+
+**If 100% coverage:** Proceed to next step  
+**If partial coverage:** Offer to create missing specs or auto-generate IDs
+
+---
+
+## NEXT STEP
+
+Once all components have OBJECT IDs:
+
+**→ Proceed to [Step 4: Generate & Validate](./step-04-generate-validate.md)**
+
+---
+
+## OUTPUT AT THIS POINT
+
+You now have:
+- ✅ MCP connection verified
+- ✅ Export scenario identified
+- ✅ OBJECT IDs assigned to all components
+- ✅ ID naming pattern established
+
+Still need:
+- ⏸️ HTML generated with proper IDs
+- ⏸️ Validation completed
+- ⏸️ Final export executed
+
+---
+
+*Step 3 complete - Specifications ready*

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-01-analyze-code.md

@@ -0,0 +1,62 @@
+# Substep 3.1: Analyze Code
+
+**Parent Step:** Prepare Specifications
+
+---
+
+## YOUR TASK
+
+Extract component information from code to create specifications.
+
+---
+
+## EXECUTION
+
+<output>Analyzing component code to create specifications...</output>
+
+<action>
+Analyze the component(s) that need OBJECT IDs:
+
+1. **Component Structure:**
+   - Identify component name and file location
+   - Map parent/child relationships
+   - Note component hierarchy
+
+2. **Props & States:**
+   - Extract available props
+   - Identify state variations (hover, active, disabled, focus, etc.)
+   - Note conditional rendering logic
+
+3. **Visual Properties:**
+   - Extract CSS classes used
+   - Note inline styles
+   - Identify design tokens/CSS variables referenced
+   - Document colors, spacing, typography
+
+4. **Content:**
+   - Extract text content
+   - Note language variations (if i18n present)
+   - Identify dynamic vs. static content
+
+5. **Behavior:**
+   - Document event handlers
+   - Note interactive elements
+   - Identify navigation/routing
+</action>
+
+<output>**Analysis Complete**
+
+Found components:
+{list of components analyzed}
+
+Key findings:
+- States identified: {list}
+- CSS classes: {list}
+- Content variations: {list}
+</output>
+
+---
+
+## NEXT SUBSTEP
+
+**→ Proceed to [Substep 3.2: Generate OBJECT IDs](./substep-02-generate-ids.md)**

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-02-generate-ids.md

@@ -0,0 +1,69 @@
+# Substep 3.2: Generate OBJECT IDs
+
+**Parent Step:** Prepare Specifications
+
+---
+
+## YOUR TASK
+
+Create OBJECT IDs following project naming conventions.
+
+---
+
+## EXECUTION
+
+<action>
+Determine the project's naming pattern by analyzing existing OBJECT IDs in specifications:
+
+**Pattern A - Page-based:**
+- Format: `{page}-{section}-{element}`
+- Example: `start-hero-cta`, `start-message-headline`
+- Use when: Exporting full pages or page sections
+
+**Pattern B - Component-based:**
+- Format: `{component}-{variant}-{state}`
+- Example: `btn-cta-primary-hover`, `input-text-disabled`
+- Use when: Exporting design system components
+
+**Pattern C - Hierarchical:**
+- Format: `{parent}-{child}-{grandchild}`
+- Example: `header-nav-menu-item`, `footer-social-icon-twitter`
+- Use when: Exporting component blocks with nested elements
+</action>
+
+<output>**Detected Naming Pattern:** {pattern-type}
+
+Generating OBJECT IDs...</output>
+
+<action>
+FOR EACH component without OBJECT ID:
+  1. Identify component type and context
+  2. Apply naming pattern
+  3. Ensure uniqueness
+  4. Add state suffix if applicable
+  
+Example generation:
+  Component: Language selector button
+  Pattern: Component-based
+  Base ID: language-selector-button
+  
+  With states:
+  - language-selector-button-default
+  - language-selector-button-open
+  - language-selector-icon
+  - language-selector-dropdown
+  - language-selector-item-en
+  - language-selector-item-se
+</action>
+
+<output>**Generated OBJECT IDs:**
+
+{list of generated IDs with descriptions}
+
+Total: {count} OBJECT IDs created</output>
+
+---
+
+## NEXT SUBSTEP
+
+**→ Proceed to [Substep 3.3: Create Specification Document](./substep-03-create-spec.md)**

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-03-create-spec.md

@@ -0,0 +1,98 @@
+# Substep 3.3: Create Specification Document
+
+**Parent Step:** Prepare Specifications
+
+---
+
+## YOUR TASK
+
+Generate a specification document with the generated OBJECT IDs.
+
+---
+
+## EXECUTION
+
+<action>
+Create specification document using the project's specification format.
+
+Determine appropriate location:
+- Design system component → `docs/D-Design-System/03-Atomic-Components/{category}/`
+- Page component → `docs/C-Scenarios/{scenario}/{page}/`
+- Shared component → `docs/D-Design-System/04-Molecules/` or `05-Organisms/`
+</action>
+
+<output>Creating specification document...</output>
+
+<action>
+Generate specification with this structure:
+
+```markdown
+# {Component/Page Name}
+
+**OBJECT ID**: `{primary-object-id}`
+
+## Purpose
+
+{Brief description of component purpose extracted from code analysis}
+
+## Structure
+
+- **HTML Tag**: `<{tag}>`
+- **CSS Class**: `.{class-name}`
+- **Component File**: `{file-path}`
+- **OBJECT ID**: `{object-id}`
+
+## Visual Style
+
+- **Typography**: {font-family}, {size}, {weight}, {color}
+- **Colors**: 
+  - Background: {color}
+  - Border: {color}
+  - Text: {color}
+- **Spacing**: 
+  - Padding: {values}
+  - Margin: {values}
+- **Layout**: {display}, {positioning}
+
+## States
+
+{For each state variation}
+
+### {State Name}
+- **OBJECT ID**: `{component-id-state}`
+- **Visual Changes**: {description}
+- **Trigger**: {user action or condition}
+
+## Behavior
+
+{Interactive behavior description from code analysis}
+
+## Content
+
+{Text content and variations}
+
+- **EN**: "{english-content}"
+- **SE**: "{swedish-content}" (if applicable)
+
+## Implementation Notes
+
+{Any technical details from code analysis}
+```
+
+Save to: `{determined-file-path}`
+</action>
+
+<output>✅ Specification document created:
+
+**Location**: {file-path}
+
+**OBJECT IDs defined:**
+{list of all OBJECT IDs in the spec}
+
+**Coverage**: {count} components documented</output>
+
+---
+
+## NEXT SUBSTEP
+
+**→ Proceed to [Substep 3.4: Review with User](./substep-04-review-spec.md)**

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-04-review-spec.md

@@ -0,0 +1,86 @@
+# Substep 3.4: Review with User
+
+**Parent Step:** Prepare Specifications
+
+---
+
+## YOUR TASK
+
+Present the generated specification to the user for approval.
+
+---
+
+## EXECUTION
+
+<output>📝 **Generated Specification Document**
+
+I've created a specification for {component-name}:
+
+**Location**: {file-path}
+
+**OBJECT IDs generated:**
+{list of generated IDs with brief descriptions}
+
+**Naming pattern used**: {pattern-description}
+
+**Components covered**: {count}</output>
+
+<ask>Would you like to:
+1. **Approve and proceed** - Use these OBJECT IDs for the export
+2. **Modify IDs** - Adjust the naming before proceeding
+3. **Review document** - See the full specification first
+
+Choice [1/2/3]:</ask>
+
+---
+
+## HANDLE USER CHOICE
+
+### Choice 1: Approve
+
+<output>✅ Specifications approved!
+
+Proceeding with these OBJECT IDs for the Code to Figma export.</output>
+
+**→ Return to [Step 3: Prepare Specifications](../step-03-prepare-specifications.md) and proceed to Step 4**
+
+---
+
+### Choice 2: Modify IDs
+
+<ask>Which OBJECT IDs would you like to modify?
+
+Please specify:
+- Current ID: {id}
+- New ID: {new-id}
+
+Or describe the naming change you'd like to make.</ask>
+
+<action>
+Update OBJECT IDs based on user feedback.
+Regenerate specification document.
+Return to review.
+</action>
+
+---
+
+### Choice 3: Review Document
+
+<action>
+Display the full specification document content.
+</action>
+
+<ask>After reviewing, would you like to:
+1. Approve and proceed
+2. Modify IDs
+3. Cancel and create specifications manually
+
+Choice [1/2/3]:</ask>
+
+**Handle choice accordingly.**
+
+---
+
+## COMPLETION
+
+Once approved, return to Step 3 with finalized OBJECT IDs ready for HTML generation.

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-04-generate-validate.md

@@ -0,0 +1,207 @@
+# Step 4: Generate & Validate
+
+**Progress: Step 4 of 5** - Next: Execute Export
+
+**Duration:** 5-10 minutes
+
+---
+
+## YOUR TASK
+
+Generate Figma-compatible HTML with proper OBJECT IDs and validate before export.
+
+---
+
+## GOAL
+
+Create clean, validated HTML that will render correctly in Figma with proper layer naming.
+
+---
+
+## EXECUTION
+
+### Generate HTML Structure
+
+<action>
+Generate HTML with OBJECT IDs from specifications:
+
+1. Create root container with export name
+2. Add state/variant containers for each component
+3. Apply OBJECT IDs from specification mapping
+4. Include state labels for clarity
+5. Add proper semantic HTML tags
+</action>
+
+**HTML Structure Template:**
+```html
+<div id="{scenario-name}-export">
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family={Font}');
+    /* Component styles with hex colors, px values */
+  </style>
+  
+  <div id="{component}-{state}-container">
+    <div class="state-label">{State Name}</div>
+    <{tag} id="{object-id}" class="{css-class}">
+      {content}
+    </{tag}>
+  </div>
+</div>
+```
+
+---
+
+### Apply Styling Requirements
+
+<action>
+Convert code styles to Figma-compatible CSS:
+
+✅ Fonts:
+  - Use Google Fonts only
+  - Import in <style> block
+
+✅ Colors:
+  - Convert CSS variables to hex values
+  - var(--brown-dark) → #2F1A0C
+  - var(--cream-light) → #FEF3CF
+
+✅ Spacing:
+  - Convert rem/em to pixels
+  - 1.5rem → 24px
+  - 2em → 32px
+
+✅ Layout:
+  - Use inline styles or <style> block
+  - Simple flexbox/grid only
+  - Avoid complex positioning
+</action>
+
+---
+
+### Validation Checks
+
+<output>Running pre-export validation...</output>
+
+<action>
+Validate generated HTML:
+
+1. ✅ Specification Coverage
+   - All components have OBJECT IDs
+   - IDs match specification exactly
+   - No duplicate IDs
+
+2. ✅ ID Naming Convention
+   - IDs follow project pattern
+   - Consistent naming across export
+   - State suffixes applied correctly
+
+3. ✅ HTML Structure
+   - Semantic HTML tags used
+   - Proper element hierarchy
+   - Container elements present
+
+4. ✅ Styling Compatibility
+   - Google Fonts used
+   - Hex colors (no CSS variables)
+   - Pixel values (no rem/em)
+   - Clean, minimal markup
+
+5. ✅ Content Completeness
+   - Text matches specifications
+   - No placeholder content
+   - Language variations included (if applicable)
+</action>
+
+---
+
+### Validation Report
+
+<output>✅ Pre-Export Validation Report
+
+📋 Specification Coverage:
+  ✅ {count} components with OBJECT IDs
+  ✅ 100% coverage achieved
+
+🔍 ID Validation:
+  ✅ No duplicate IDs found
+  ✅ Naming convention followed
+  ✅ {count} unique IDs ready
+
+🏗️ Structure Validation:
+  ✅ Semantic HTML used
+  ✅ Proper element hierarchy
+
+🎨 Styling Validation:
+  ✅ Google Fonts configured
+  ✅ Hex colors used
+  ✅ Pixel spacing values
+  ✅ Figma-compatible CSS
+
+📝 Content Validation:
+  ✅ Specification content matched
+  ✅ No placeholder text
+
+⚠️ Warnings: {count}
+{list of non-blocking warnings}
+
+❌ Errors: {count}
+{list of blocking errors}
+
+Ready to proceed to export? (Yes/No)</output>
+
+<ask>Proceed with export? [Yes/Fix Errors/Cancel]:</ask>
+
+---
+
+### Handle Validation Failures
+
+**If errors found:**
+
+<output>❌ Validation Errors Must Be Resolved
+
+Error Type: {error-type}
+Affected Components: {list}
+
+Would you like me to:
+1. Auto-fix errors (if possible)
+2. Guide you through manual fixes
+3. Skip problematic components
+4. Cancel export</output>
+
+**Auto-fix capabilities:**
+- Convert CSS variables to hex
+- Convert rem/em to pixels
+- Add missing IDs based on class names
+- Fix duplicate IDs with suffixes
+
+**Manual fix required:**
+- Semantic HTML structure issues
+- Missing specification content
+- Complex CSS incompatible with Figma
+
+---
+
+## NEXT STEP
+
+Once validation passes:
+
+**→ Proceed to [Step 5: Execute Export](./step-05-execute-export.md)**
+
+---
+
+## OUTPUT AT THIS POINT
+
+You now have:
+- ✅ MCP connection verified
+- ✅ Export scenario identified
+- ✅ OBJECT IDs assigned
+- ✅ HTML generated with proper IDs
+- ✅ Validation completed successfully
+
+Still need:
+- ⏸️ Final export executed
+- ⏸️ Export verified in Figma
+
+---
+
+*Step 4 complete - Ready to export*

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-05-execute-export.md

@@ -0,0 +1,229 @@
+# Step 5: Send to Figma
+
+**Progress: Step 5 of 5** - Final Step
+
+**Duration:** 2-5 minutes
+
+---
+
+## YOUR TASK
+
+Send the code to Figma and verify success.
+
+---
+
+## GOAL
+
+Send the validated HTML to Figma and confirm the layers appear with proper OBJECT ID naming.
+
+---
+
+## EXECUTION
+
+### Prepare Export Parameters
+
+<action>
+Prepare MCP tool call parameters:
+
+- name: Descriptive title for Figma layer
+  Format: "{Component/Page Name} - {Purpose}"
+  Example: "CTA Button States - Design System"
+
+- html: Complete validated HTML from Step 4
+  
+- intoNodeId: (optional) Only if updating existing Figma layer
+</action>
+
+---
+
+### Execute Export
+
+<output>Executing export to Figma...</output>
+
+<action>
+Call MCP tool:
+
+```javascript
+mcp2_import-html({
+  name: "{export-name}",
+  html: `{validated-html}`
+})
+```
+
+Wait for response.
+</action>
+
+---
+
+### Verify Export Response
+
+**Expected Response:**
+```json
+{
+  "node": {
+    "id": "X:XXX",
+    "name": "{export-name} by html.to.design...",
+    "type": "SECTION"
+  }
+}
+```
+
+**Success Indicators:**
+- ✅ Node ID returned
+- ✅ No error message
+- ✅ Response contains node object
+
+**Failure Indicators:**
+- ❌ Error message in response
+- ❌ No node ID
+- ❌ Timeout or connection error
+
+---
+
+### Verify in Figma
+
+<ask>Please check your Figma file:
+
+1. Look for a new layer named "{export-name} by html.to.design..."
+2. Expand the layer to see the component structure
+3. Check that layer names match the OBJECT IDs we defined
+
+Can you see the export in Figma with proper layer names? [Yes/No]:</ask>
+
+**Wait for user confirmation.**
+
+---
+
+### Success Report
+
+**If user confirms success:**
+
+<output>✅ Export Successful!
+
+**Export Details:**
+- Name: {export-name}
+- Node ID: {node-id}
+- Components: {count}
+- OBJECT IDs used: {list}
+
+**Layer Names in Figma:**
+{list of OBJECT IDs that became layer names}
+
+The export is now available in your Figma file. Layer names match the specification OBJECT IDs for easy identification and traceability.
+
+**Next Steps:**
+1. Review the export in Figma
+2. Make any visual adjustments needed
+3. Use Figma Import workflow to sync changes back to code (if needed)
+4. Update design system based on refinements
+
+**Documentation:**
+- Specification: {spec-file-path}
+- Export manifest: {manifest if created}
+- OBJECT IDs: {count} total</output>
+
+---
+
+### Troubleshooting
+
+**If user reports export not visible:**
+
+<output>Troubleshooting export visibility...</output>
+
+<action>
+Check common issues:
+
+1. **Figma not open**
+   - Ensure Figma is running
+   - Ensure html.to.design plugin is active
+   - Retry export
+
+2. **Wrong file**
+   - Check which Figma file is active
+   - Ensure plugin is running in correct file
+   - Switch to correct file and retry
+
+3. **Layer hidden or collapsed**
+   - Look in layers panel (left sidebar)
+   - Expand all groups/sections
+   - Search for layer name
+
+4. **Export to different page**
+   - Check all pages in Figma file
+   - Plugin may have exported to active page
+   - Look through all pages
+
+5. **Connection issue**
+   - Check MCP server connection
+   - Restart plugin
+   - Retry export
+</action>
+
+<ask>After checking these items, can you see the export? [Yes/Still No]:</ask>
+
+**If still no:** Provide detailed error report and suggest manual verification steps.
+
+---
+
+## COMPLETION
+
+<output>🎉 Code to Figma Workshop Complete!
+
+**Summary:**
+- ✅ MCP connection established
+- ✅ Export scenario identified: {scenario}
+- ✅ Specifications prepared with OBJECT IDs
+- ✅ HTML generated and validated
+- ✅ Export executed successfully
+- ✅ Verified in Figma
+
+**Achievements:**
+- {count} components exported
+- {count} OBJECT IDs defined
+- Design-code parity maintained
+- Traceability established
+
+**Files Created/Updated:**
+{list of specification files created}
+
+**Figma Output:**
+- Layer: {export-name}
+- Node ID: {node-id}
+- Location: {Figma file name}
+
+Thank you for using the Figma Export workflow! 🎨</output>
+
+---
+
+## NEXT ACTIONS
+
+**Recommended next steps:**
+
+1. **Review in Figma**
+   - Check visual accuracy
+   - Verify all states/variations
+   - Note any design improvements needed
+
+2. **Design Refinement** (if needed)
+   - Make visual adjustments in Figma
+   - Update colors, spacing, typography
+   - Refine component states
+
+3. **Sync Back to Code** (if changes made)
+   - Use Figma Import workflow
+   - Extract updated design specs
+   - Update CSS/components
+
+4. **Update Design System**
+   - Document new patterns
+   - Add components to library
+   - Update design tokens
+
+5. **Share with Team**
+   - Present to stakeholders
+   - Get design approval
+   - Coordinate with developers
+
+---
+
+*Workflow complete - Export successful!*

src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/workflow.md

@@ -0,0 +1,64 @@
+# Code to Figma Workshop - Entry Point
+
+**Purpose:** Send code implementations to Figma for design review, documentation, and visual iteration
+
+**Tool:** html.to.design MCP Server  
+**Direction:** Code → Figma
+
+---
+
+## Overview
+
+This workshop guides AI agents through sending code to Figma using a **specification-driven approach** where component naming and structure are derived from project specifications.
+
+### When to Send Code to Figma
+
+Send code to Figma when:
+- ✅ Component states need visual documentation (hover, active, disabled, etc.)
+- ✅ Design system components require Figma library representation
+- ✅ Prototype pages need designer review and feedback
+- ✅ Visual adjustments are easier to iterate in Figma than code
+- ✅ Design-code parity documentation is needed
+
+---
+
+## Agent Instructions
+
+**Execute steps sequentially. Do not skip steps.**
+
+Each step:
+1. Completes one atomic task
+2. Validates before proceeding
+3. Captures output for next step
+4. Moves to next step ONLY when complete
+
+**Do not look ahead. Execute one step at a time.**
+
+---
+
+## Workshop Structure
+
+**Step 1: Connection Check** (~5-10 min)
+- Verify MCP connection and guide setup if needed
+
+**Step 2: Identify Export Type** (~2-3 min)
+- Determine what type of export (prototype page, design system component, or frontend view)
+
+**Step 3: Prepare Specifications** (~5-15 min)
+- Find or create specifications with OBJECT IDs for proper Figma naming
+
+**Step 4: Generate & Validate** (~5-10 min)
+- Generate Figma-compatible HTML and validate before export
+
+**Step 5: Execute Export** (~2-5 min)
+- Execute export and verify success in Figma
+
+---
+
+## Begin Workshop
+
+**→ Start with [Step 1: Connection Check](./step-01-connection-check.md)**
+
+---
+
+*Follow the steps. Trust the process.*

src/modules/wds/workflows/5-design-system/figma-integration/figma-to-code/figma-integration-guide.md

@@ -0,0 +1,37 @@
+# Figma to Code Workshop
+
+**Status:** Coming Soon
+
+**Purpose:** Extract design specifications from Figma and implement them in code
+
+**Tool:** Figma Desktop MCP Server  
+**Direction:** Figma → Code
+
+---
+
+## Overview
+
+This workshop will guide AI agents through importing design specifications from Figma to generate or update code implementations.
+
+### When to Use Figma to Code
+
+Import from Figma when:
+- ✅ Designer has updated visual specifications in Figma
+- ✅ New design system components need implementation
+- ✅ Design tokens (colors, spacing, typography) need extraction
+- ✅ Component states have been refined visually
+- ✅ Design-code sync is needed after visual iteration
+
+---
+
+## Planned Workflow
+
+1. **Connection Check** - Verify Figma Desktop MCP server
+2. **Select Figma Node** - Identify what to import
+3. **Extract Design Specs** - Get colors, spacing, typography, layout
+4. **Generate/Update Code** - Create or update components
+5. **Verify Implementation** - Compare code output to Figma design
+
+---
+
+*This workshop will be developed to complement the Code to Figma workflow.*