whiteport-design-studio 0.1.0

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

@@ -0,0 +1,458 @@
+# Figma Integration - Summary
+
+**Last Updated:** January 9, 2026  
+**Version:** WDS v6  
+**Status:** Active Development
+
+---
+
+## Overview
+
+This integration enables bidirectional workflow between code and Figma for design system development and visual refinement.
+
+### Bidirectional Workflow
+
+```
+Code ⇄ Figma
+```
+
+**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.
+
+---
+
+## Workshop Structure
+
+### Code to Figma (C2F) Workshop
+**Location:** `code-to-figma/`
+
+**Purpose:** Send code implementations to Figma for design review, documentation, and visual iteration
+
+**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:**
+- Specification-driven OBJECT ID naming
+- Three export scenarios with specific ID patterns
+- Automated validation before export
+- Reverse engineering for missing specifications
+
+---
+
+### Figma to Code (F2C) Workshop
+**Location:** `figma-to-code/`
+
+**Status:** Coming Soon
+
+**Purpose:** Import design specifications from Figma to generate or update code implementations
+
+**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
+
+---
+
+## Reference Documentation
+
+**Location:** `reference/`
+
+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
+
+```
+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
+```
+
+---
+
+## Core Concepts
+
+### The Missing Dimension
+
+**Before:** WDS created specifications and functional prototypes, but visual design creation was manual
+
+**After:** WDS now supports iterative visual refinement through Figma extraction
+
+### Design System Evolution
+
+**Key Principle:** Design system grows organically as prototypes are built
+
+**Process:**
+1. Create prototype with existing design system (may look basic)
+2. Extract to Figma when gaps identified
+3. Refine visuals and create missing components
+4. Update design system with new tokens/components
+5. Re-render prototype with enhanced design system
+6. Iterate until polished
+
+### When to Extract
+
+**Extract when:**
+- Design system is incomplete
+- Prototype needs visual polish
+- New components required
+- Stakeholder presentation needed
+
+**Don't extract when:**
+- Design system covers all needs
+- Prototype looks sufficient
+- Rapid iteration more important
+- Early exploration phase
+
+---
+
+## Tool Integration
+
+### html.to.design
+
+**Role:** Convert HTML prototypes to Figma for visual refinement
+
+**Process:**
+1. Upload HTML prototype
+2. Configure conversion options
+3. Import to Figma
+4. Refine design
+5. Extract design system updates
+
+**Benefits:**
+- Preserves layout structure
+- Converts CSS to Figma styles
+- Maintains element hierarchy
+- Enables visual refinement
+
+### Area Tag System
+
+**Role:** Precise region mapping for image-based prototypes
+
+**Usage:**
+- Map clickable regions on images
+- Include Object IDs for traceability
+- Extract coordinates via dev mode
+- Document region mappings
+
+**Integration:**
+- Works with dev-mode.js component
+- Supports image-based prototypes
+- Enables precise click mapping
+
+### Dev Mode Component
+
+**Role:** Extract Object IDs and area coordinates from prototypes
+
+**Features:**
+- Shift + Click to copy Object IDs
+- Visual highlights
+- Area tag detection
+- Coordinate extraction
+
+**Benefit:** Maintains traceability through Figma extraction
+
+---
+
+## Workflow Integration
+
+### Phase 4: UX Design
+
+**Updated Step 4D (Prototype):**
+- Create functional prototype
+- Test functionality
+- **NEW:** Assess visual quality
+- **NEW:** Option to extract to Figma
+- Continue to PRD update
+
+### Phase 5: Design System
+
+**New Workflow Branch:**
+- Existing: Component specification → Design system
+- Existing: Figma manual creation → Design system
+- **NEW:** Prototype extraction → Figma → Design system
+
+### Iteration Loop
+
+**Complete Cycle:**
+```
+1. Sketch (concept)
+2. Specification (detailed)
+3. Prototype (functional)
+4. Figma extraction (if needed)
+5. Visual refinement
+6. Design system update
+7. Re-render prototype
+8. Assess → Iterate or Complete
+```
+
+---
+
+## Benefits
+
+### For Designers
+
+**Flexibility:**
+- Start with functional prototypes
+- Refine visuals when needed
+- Iterate incrementally
+- Build design system organically
+
+**Efficiency:**
+- Don't need complete design system upfront
+- Extract only when necessary
+- Reuse refined components
+- Reduce rework
+
+### For Teams
+
+**Collaboration:**
+- Shared design language
+- Clear handoff process
+- Bidirectional sync
+- Maintained traceability
+
+**Quality:**
+- Polished final products
+- Consistent design system
+- Professional visuals
+- Stakeholder-ready
+
+### For Projects
+
+**Speed:**
+- Faster initial prototypes
+- Iterative refinement
+- Parallel work streams
+- Reduced bottlenecks
+
+**Flexibility:**
+- Adapt to changing requirements
+- Grow design system as needed
+- Balance speed and polish
+- Ship working products
+
+---
+
+## Public Release Readiness
+
+### Documentation Status
+
+✅ **Complete:**
+- Prototype-to-Figma workflow
+- Decision guide
+- Tools reference
+- Phase 4D integration
+- Phase 5 README update
+
+✅ **Tested:**
+- Workflow logic validated
+- Integration points confirmed
+- Decision framework practical
+- Tool capabilities verified
+
+✅ **Ready for:**
+- Public documentation
+- User testing
+- Team adoption
+- Production use
+
+### What's Not Included
+
+**Out of Scope:**
+- MagicPatterns integration (not needed with html.to.design)
+- Automated extraction (manual process documented)
+- Real-time sync (manual iteration cycle)
+
+**Future Enhancements:**
+- Automated design token extraction
+- Figma plugin for WDS
+- Real-time bidirectional sync
+- AI-powered component matching
+
+---
+
+## Migration Notes
+
+### For Existing WDS Users
+
+**No Breaking Changes:**
+- Existing workflows continue to work
+- New workflow is optional
+- Backward compatible
+- Incremental adoption
+
+**How to Adopt:**
+1. Read prototype-to-Figma workflow
+2. Try with one prototype
+3. Refine in Figma
+4. Update design system
+5. Re-render and compare
+6. Expand to more pages
+
+### For New WDS Users
+
+**Recommended Approach:**
+1. Start with first page
+2. Create basic prototype
+3. Extract to Figma
+4. Build design system foundation
+5. Use for subsequent pages
+6. Extract only when gaps found
+
+---
+
+## Success Metrics
+
+### Quality Indicators
+
+✅ Prototypes look polished  
+✅ Design system is comprehensive  
+✅ Figma and code are in sync  
+✅ Object IDs maintained throughout  
+✅ Iterations are productive  
+✅ Team aligned on visual direction
+
+### Efficiency Indicators
+
+✅ Fewer refinement cycles needed  
+✅ Design system grows organically  
+✅ Reusable components identified  
+✅ Faster subsequent prototypes  
+✅ Reduced rework
+
+---
+
+## Next Steps
+
+### For Documentation
+
+1. ✅ Core workflow documentation complete
+2. ✅ Decision guides created
+3. ✅ Tools reference documented
+4. ✅ Integration points updated
+5. 🔄 Session logs cleanup (in progress)
+6. ⏳ User testing and feedback
+7. ⏳ Video tutorials (future)
+8. ⏳ Example projects (future)
+
+### For Implementation
+
+1. ✅ Workflow files created
+2. ✅ Phase 4D updated
+3. ✅ Phase 5 updated
+4. ⏳ Test with real projects
+5. ⏳ Gather user feedback
+6. ⏳ Refine based on usage
+7. ⏳ Create example case studies
+
+---
+
+## Key Takeaways
+
+### The Complete WDS Flow
+
+**Concept-First Approach:**
+1. Sketch and specification are source of truth
+2. Generate functional prototypes from specs
+3. Apply design system (may be incomplete initially)
+4. Extract to Figma when visual refinement needed
+5. Refine design and extend design system
+6. Re-render with enhanced design system
+7. Iterate until polished
+
+### Design System Philosophy
+
+**Just-In-Time Design Definitions:**
+- Don't need complete design system upfront
+- Build definitions as needed
+- Extract from working prototypes
+- Grow organically with product
+- Reduce upfront investment
+
+### Iterative Refinement
+
+**Balanced Approach:**
+- Functional first, polish later
+- Extract strategically, not automatically
+- Iterate incrementally
+- Ship working products
+- Balance speed and quality
+
+---
+
+## Contact and Support
+
+**Documentation Location:**
+- `workflows/5-design-system/figma-integration/`
+
+**Related Documentation:**
+- Phase 4: UX Design workflows
+- Phase 5: Design System workflows
+- Interactive Prototypes guides
+- Figma Integration guides
+
+**Questions or Issues:**
+- Review decision guide for common scenarios
+- Check tools reference for troubleshooting
+- Follow workflow documentation step-by-step
+- Test with simple prototype first
+
+---
+
+**This integration completes the WDS design workflow, enabling teams to create polished, production-ready designs through iterative refinement of functional prototypes.**
+
+---
+
+## Version History
+
+**v1.0 - January 8, 2026**
+- Initial release
+- Prototype-to-Figma workflow
+- Decision guide
+- Tools reference
+- Phase 4D and Phase 5 integration
+
+**Future Versions:**
+- User feedback integration
+- Enhanced automation
+- Additional tool integrations
+- Example case studies

package/src/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*

package/src/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)**

package/src/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)**

package/src/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