whiteport-design-studio 0.1.0

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

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

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

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