whiteport-design-studio 0.1.0

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

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

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

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

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

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