From 7c2f0cfbc4e9f944958786b297760c63d45a8ad8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Fri, 9 Jan 2026 21:10:47 +0100 Subject: [PATCH] Figma integration --- .eslintignore | 2 + eslint.config.mjs | 2 + src/modules/wds/README.md | 190 ++++++++++++--- .../wds/agents/eira-visual-designer.md | 24 +- .../data/presentations/freya-presentation.md | 2 + .../data/presentations/idunn-presentation.md | 2 + .../data/presentations/mimir-presentation.md | 7 +- .../data/presentations/saga-presentation.md | 2 + ...26-01-04-eira-visual-design-integration.md | 49 +++- .../method/phase-5-design-system-guide.md | 20 +- src/modules/wds/docs/tools/figma-mcp.md | 125 ++++++++++ src/modules/wds/docs/tools/nanobanana.md | 16 +- .../figma-integration/INTEGRATION-SUMMARY.md | 165 ++++++------- .../steps/step-01-connection-check.md | 118 +++++++++ .../substep-01-plugin-installation.md | 37 +++ .../substep-02-activate-plugin.md | 37 +++ .../step-01-substeps/substep-03-verify-mcp.md | 51 ++++ .../steps/step-02-identify-export-type.md | 161 ++++++++++++ .../steps/step-03-prepare-specifications.md | 138 +++++++++++ .../substep-01-analyze-code.md | 62 +++++ .../substep-02-generate-ids.md | 69 ++++++ .../substep-03-create-spec.md | 98 ++++++++ .../substep-04-review-spec.md | 86 +++++++ .../steps/step-04-generate-validate.md | 207 ++++++++++++++++ .../steps/step-05-execute-export.md | 229 ++++++++++++++++++ .../code-to-figma/workflow.md | 64 +++++ .../figma-to-code/figma-integration-guide.md | 37 +++ .../{ => reference}/figma-designer-guide.md | 0 .../{ => reference}/figma-mcp-integration.md | 0 .../{ => reference}/mcp-server-integration.md | 0 .../prototype-to-figma-workflow.md | 0 .../{ => reference}/tools-reference.md | 0 .../when-to-extract-decision-guide.md | 0 33 files changed, 1852 insertions(+), 148 deletions(-) create mode 100644 .eslintignore create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-connection-check.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-01-plugin-installation.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-02-activate-plugin.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-03-verify-mcp.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-02-identify-export-type.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-prepare-specifications.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-01-analyze-code.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-02-generate-ids.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-03-create-spec.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-04-review-spec.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-04-generate-validate.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-05-execute-export.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/workflow.md create mode 100644 src/modules/wds/workflows/5-design-system/figma-integration/figma-to-code/figma-integration-guide.md rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/figma-designer-guide.md (100%) rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/figma-mcp-integration.md (100%) rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/mcp-server-integration.md (100%) rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/prototype-to-figma-workflow.md (100%) rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/tools-reference.md (100%) rename src/modules/wds/workflows/5-design-system/figma-integration/{ => reference}/when-to-extract-decision-guide.md (100%) diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 00000000..dc7164a0 --- /dev/null +++ b/.eslintignore @@ -0,0 +1,2 @@ +# Figma MCP Server - external project with different config +figma-mcp-server/ diff --git a/eslint.config.mjs b/eslint.config.mjs index e361b1cd..72529e31 100644 --- a/eslint.config.mjs +++ b/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/**', diff --git a/src/modules/wds/README.md b/src/modules/wds/README.md index e73055e7..9b257d39 100644 --- a/src/modules/wds/README.md +++ b/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 + +οΏ½ **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 | -| ------------------ | ----- | ---------------------------------- | -| `A-Product-Brief/` | 1 | Strategic foundation & vision | -| `B-Trigger-Map/` | 2 | Business goals, personas, drivers | -| `C-Scenarios/` | 4 | Visual specifications & sketches | -| `D-PRD/` | 3 | Product requirements documentation | -| `D-Design-System/` | 5 | Component library & design tokens | -| `E-UI-Roadmap/` | 6 | Development integration bridge | +| Folder | Phase | Purpose | Timing | +| ------------------ | ----- | -------------------------------------------- | ------------------- | +| `A-Product-Brief/` | 1 | Strategic foundation & vision | Start here | +| `B-Trigger-Map/` | 2 | User psychology & business goals | After Phase 1 | +| `C-Scenarios/` | 4 | UX specifications (HOW it works) | After Phase 2 | +| `D-Design-System/` | 5 | Visual identity & components (HOW it looks) | **Anytime** 🎨 | +| `D-PRD/` | 3 | Technical requirements (optional) | Before development | +| `E-UI-Roadmap/` | 6 | Development handoff | After Phase 4 | -## Phases +## 🎯 Design Phases -1. **Product Exploration** β†’ `A-Product-Brief/` -2. **User Research** β†’ `B-Trigger-Map/` -3. **Requirements** β†’ `D-PRD/` -4. **Conceptual Design** β†’ `C-Scenarios/` (with optional Figma visual refinement) -5. **Component Design** β†’ `D-Design-System/` (grows organically via Figma integration) -6. **Dev Integration** β†’ `E-UI-Roadmap/` +### Core Workflow + +**Phase 1: Product Exploration** β†’ `A-Product-Brief/` +Define vision, positioning, and success criteria + +**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 -- **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 +### Visual Design Tools -## 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 / +``` + +### 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 + --- Part of the BMad ecosystem β€’ Contributed by Whiteport Collective diff --git a/src/modules/wds/agents/eira-visual-designer.md b/src/modules/wds/agents/eira-visual-designer.md index 70b6a893..43885e21 100644 --- a/src/modules/wds/agents/eira-visual-designer.md +++ b/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: -[Project name] +**Phase:** 5 - Design System (Visual Design Exploration) +**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?] diff --git a/src/modules/wds/data/presentations/freya-presentation.md b/src/modules/wds/data/presentations/freya-presentation.md index c4271dee..8fb9f2c3 100644 --- a/src/modules/wds/data/presentations/freya-presentation.md +++ b/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! diff --git a/src/modules/wds/data/presentations/idunn-presentation.md b/src/modules/wds/data/presentations/idunn-presentation.md index 6686cac2..e7a4c1b4 100644 --- a/src/modules/wds/data/presentations/idunn-presentation.md +++ b/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! diff --git a/src/modules/wds/data/presentations/mimir-presentation.md b/src/modules/wds/data/presentations/mimir-presentation.md index 45afe719..59f1776d 100644 --- a/src/modules/wds/data/presentations/mimir-presentation.md +++ b/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 diff --git a/src/modules/wds/data/presentations/saga-presentation.md b/src/modules/wds/data/presentations/saga-presentation.md index 23a7da94..457ea841 100644 --- a/src/modules/wds/data/presentations/saga-presentation.md +++ b/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! diff --git a/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/2026-01-04-eira-visual-design-integration.md b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/2026-01-04-eira-visual-design-integration.md index 0cd64172..b19ecb4c 100644 --- a/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/2026-01-04-eira-visual-design-integration.md +++ b/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 diff --git a/src/modules/wds/docs/method/phase-5-design-system-guide.md b/src/modules/wds/docs/method/phase-5-design-system-guide.md index 4958d150..477fa334 100644 --- a/src/modules/wds/docs/method/phase-5-design-system-guide.md +++ b/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) -- When establishing brand identity -- When exploring multiple visual directions +- **AFTER Phase 1 & 2** (Product Brief and Trigger Map must be complete first!) +- When establishing brand identity (with strategic context) +- 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/` diff --git a/src/modules/wds/docs/tools/figma-mcp.md b/src/modules/wds/docs/tools/figma-mcp.md index 10e26257..75b36e2a 100644 --- a/src/modules/wds/docs/tools/figma-mcp.md +++ b/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:** diff --git a/src/modules/wds/docs/tools/nanobanana.md b/src/modules/wds/docs/tools/nanobanana.md index 5ee437db..841f0556 100644 --- a/src/modules/wds/docs/tools/nanobanana.md +++ b/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 -- Design inspiration -- Exploring visual concepts -- Creating placeholder assets -- Brand identity exploration +- **ANYTIME** - Brand identity is independent of product strategy! +- When establishing brand identity (can be before, during, or after product work) +- When exploring multiple visual directions +- Before committing to design tokens +- Can happen before Phase 1, parallel to strategy work, or after Phase 4 **Sketch Envisioning (Alternative to Figma):** - Converting sketches to visual designs quickly diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md b/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md index e8e2c60f..3e5a4440 100644 --- a/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md +++ b/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 -**File:** `prototype-to-figma-workflow.md` +### Code to Figma (C2F) Workshop +**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:** -- When and why to extract prototypes -- Step-by-step extraction process using html.to.design -- Figma refinement techniques -- Design system update process -- Re-rendering with enhanced design system -- 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 +**Workflow Steps:** +1. Connection Check - Verify html.to.design MCP server +2. Identify Type - Determine export scenario (prototype page, design system component, or frontend view) +3. Prepare Specifications - Find or create OBJECT IDs for proper Figma layer naming +4. Generate & Validate - Create Figma-compatible HTML with validation +5. Send to Figma - Execute export and verify success **Key Features:** -- Clear decision criteria -- Red flags to avoid -- Decision matrix -- Time investment analysis -- Priority guidance +- Specification-driven OBJECT ID naming +- Three export scenarios with specific ID patterns +- Automated validation before export +- Reverse engineering for missing specifications --- -### 3. Tools Reference -**File:** `tools-reference.md` +### Figma to Code (F2C) Workshop +**Location:** `figma-to-code/` -**Purpose:** Quick reference for design tools used in WDS workflows +**Status:** Coming Soon -**Covers:** -- **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 +**Purpose:** Import design specifications from Figma to generate or update code implementations -**Key Sections:** -- Tool features and capabilities -- How to use each tool -- Best practices -- Limitations -- Integration workflows -- Troubleshooting +**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 --- -## Updated Files +## Reference Documentation -### 1. Phase 4D Prototype Workflow -**File:** `workflows/4-ux-design/substeps/4d-prototype.md` +**Location:** `reference/` -**Changes:** -- Added visual quality assessment after prototype testing -- Integrated Figma extraction option -- References to new workflow documentation -- Decision points for refinement vs completion +Supporting documentation for Figma integration workflows: + +1. **`figma-designer-guide.md`** - Guide for designers creating components in Figma +2. **`mcp-server-integration.md`** - MCP server setup and configuration +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 β†’ - Option 1: Polished (continue) - Option 2: Needs refinement (extract to Figma) - Option 3: Minor tweaks (quick CSS fixes) +figma-integration/ +β”œβ”€β”€ code-to-figma/ # C2F Workshop +β”‚ β”œβ”€β”€ workflow.md +β”‚ └── 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 diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-connection-check.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-connection-check.md new file mode 100644 index 00000000..411ab694 --- /dev/null +++ b/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 + + +Check if `mcp2_import-html` tool is accessible in current session. +Tool should be from "html.to.design MCP server" + + +**Decision Point:** +- βœ… Tool available β†’ **Skip to Step 2** +- ❌ Tool not available β†’ **Continue with substeps** + +--- + +## IF TOOL NOT AVAILABLE + +⚠️ 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? + +Proceed with setup? [Yes/No]: + +**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): + + +Execute test export: +```javascript +mcp2_import-html({ + name: "Connection Test", + html: "
βœ… Connection Test Successful
" +}) +``` + + +**Expected Response:** +```json +{ + "node": { + "id": "X:XXX", + "name": "Connection Test by html.to.design...", + "type": "SECTION" + } +} +``` + +Can you see the "Connection Test" layer in your Figma file? [Yes/No]: + +**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* diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-01-plugin-installation.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-01-plugin-installation.md new file mode 100644 index 00000000..e4b40917 --- /dev/null +++ b/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 + +**Step 1: Install html.to.design Plugin** + +Please follow these steps to install the plugin: + + +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 + + +Have you completed the plugin installation? [Yes/No]: + +**Wait for user confirmation before proceeding.** + +--- + +## NEXT SUBSTEP + +**β†’ Proceed to [Substep 1.2: Activate Plugin](./substep-02-activate-plugin.md)** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-02-activate-plugin.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-02-activate-plugin.md new file mode 100644 index 00000000..1413687a --- /dev/null +++ b/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 + +**Step 2: Activate the Plugin** + +Now let's activate the plugin in your Figma file: + + +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 + + +Can you see the html.to.design plugin panel? [Yes/No]: + +**Wait for user confirmation before proceeding.** + +--- + +## NEXT SUBSTEP + +**β†’ Proceed to [Substep 1.3: Verify MCP Configuration](./substep-03-verify-mcp.md)** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-03-verify-mcp.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-01-substeps/substep-03-verify-mcp.md new file mode 100644 index 00000000..0b07aab2 --- /dev/null +++ b/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 + +**Step 3: Verify MCP Server Configuration** + +The html.to.design MCP server should be configured in your IDE settings. + +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]: + +**Wait for user response.** + +--- + +## IF YES + +βœ… MCP server is configured. Let's test the connection. + +**β†’ Return to [Step 1: Connection Check](../step-01-connection-check.md#verification) to run test export** + +--- + +## IF NO + +⚠️ 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. + +Have you configured the MCP server? [Yes/Retry/Need Help]: + +**If Yes:** Return to verification +**If Need Help:** Provide IDE-specific configuration guidance diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-02-identify-export-type.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-02-identify-export-type.md new file mode 100644 index 00000000..620047c1 --- /dev/null +++ b/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 + + +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 + + +--- + +### Determine Scenario Type + +Based on your request, I need to determine the export type... + +**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 + +πŸ“‹ 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? + +Proceed with this scenario? [Yes/Adjust/Cancel]: + +**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* diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-prepare-specifications.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-prepare-specifications.md new file mode 100644 index 00000000..d473ff37 --- /dev/null +++ b/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 + + +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 + + +--- + +### Decision Point: Specifications Found? + +**If specifications exist with OBJECT IDs:** + +βœ… Found specification documents with OBJECT IDs: + +{list of files and IDs found} + +I'll use these OBJECT IDs for the export. + + +Extract OBJECT IDs from specifications: +- Read specification files +- Extract all OBJECT ID field values +- Map to components in code +- Store mapping for HTML generation + + +**β†’ Skip to validation and proceed to Step 4** + +--- + +**If NO specifications exist:** + +πŸ“ 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? + +Create specifications? [Yes/No]: + +**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 + + +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 + + +πŸ“‹ Specification Coverage Report: + +βœ… Components with OBJECT IDs: {count} + - {list} + +⚠️ Components missing OBJECT IDs: {count} + - {list} + +Coverage: {percentage}% + +**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* diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-01-analyze-code.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-01-analyze-code.md new file mode 100644 index 00000000..a762f1d8 --- /dev/null +++ b/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 + +Analyzing component code to create specifications... + + +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 + + +**Analysis Complete** + +Found components: +{list of components analyzed} + +Key findings: +- States identified: {list} +- CSS classes: {list} +- Content variations: {list} + + +--- + +## NEXT SUBSTEP + +**β†’ Proceed to [Substep 3.2: Generate OBJECT IDs](./substep-02-generate-ids.md)** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-02-generate-ids.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-02-generate-ids.md new file mode 100644 index 00000000..e55854c9 --- /dev/null +++ b/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 + + +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 + + +**Detected Naming Pattern:** {pattern-type} + +Generating OBJECT IDs... + + +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 + + +**Generated OBJECT IDs:** + +{list of generated IDs with descriptions} + +Total: {count} OBJECT IDs created + +--- + +## NEXT SUBSTEP + +**β†’ Proceed to [Substep 3.3: Create Specification Document](./substep-03-create-spec.md)** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-03-create-spec.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-03-create-spec.md new file mode 100644 index 00000000..8926c7ad --- /dev/null +++ b/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 + + +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/` + + +Creating specification document... + + +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}` + + +βœ… Specification document created: + +**Location**: {file-path} + +**OBJECT IDs defined:** +{list of all OBJECT IDs in the spec} + +**Coverage**: {count} components documented + +--- + +## NEXT SUBSTEP + +**β†’ Proceed to [Substep 3.4: Review with User](./substep-04-review-spec.md)** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-04-review-spec.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-03-substeps/substep-04-review-spec.md new file mode 100644 index 00000000..bc75fe63 --- /dev/null +++ b/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 + +πŸ“ **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} + +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]: + +--- + +## HANDLE USER CHOICE + +### Choice 1: Approve + +βœ… Specifications approved! + +Proceeding with these OBJECT IDs for the Code to Figma export. + +**β†’ Return to [Step 3: Prepare Specifications](../step-03-prepare-specifications.md) and proceed to Step 4** + +--- + +### Choice 2: Modify IDs + +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. + + +Update OBJECT IDs based on user feedback. +Regenerate specification document. +Return to review. + + +--- + +### Choice 3: Review Document + + +Display the full specification document content. + + +After reviewing, would you like to: +1. Approve and proceed +2. Modify IDs +3. Cancel and create specifications manually + +Choice [1/2/3]: + +**Handle choice accordingly.** + +--- + +## COMPLETION + +Once approved, return to Step 3 with finalized OBJECT IDs ready for HTML generation. diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-04-generate-validate.md b/src/modules/wds/workflows/5-design-system/figma-integration/code-to-figma/steps/step-04-generate-validate.md new file mode 100644 index 00000000..0db76a53 --- /dev/null +++ b/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 + + +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 + + +**HTML Structure Template:** +```html +
+ + +
+
{State Name}
+ <{tag} id="{object-id}" class="{css-class}"> + {content} + +
+
+``` + +--- + +### Apply Styling Requirements + + +Convert code styles to Figma-compatible CSS: + +βœ… Fonts: + - Use Google Fonts only + - Import in