whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md

@@ -0,0 +1,155 @@
+# Complexity Router Workflow
+
+**Step-by-step guided decomposition**
+
+---
+
+## Overview
+
+When a complex component is detected, the agent guides you through 3 steps:
+
+1. **WHERE** - Page context
+2. **HOW** - Visual design
+3. **WHAT** - Functional logic
+
+---
+
+## Step 1: Page Context (WHERE)
+
+**Agent asks:**
+
+1. Which page(s) does this appear on?
+2. Where on the page?
+3. How big is it?
+4. Same component on multiple pages, or page-specific?
+5. **Does CONTENT change based on page context?**
+6. **Does DATA source change based on page context?**
+
+**You answer, agent captures:**
+
+- Pages list
+- Position
+- Size
+- Reusability
+- Content varies: YES/NO
+- Data source varies: YES/NO
+
+**Result:** Page file specification
+
+---
+
+## Step 2: Visual Design (HOW)
+
+**Agent asks:**
+
+1. How many visual states?
+2. Do you have a storyboard showing states?
+3. For each state:
+   - What does it look like?
+   - What triggers this state?
+   - Can it transition to other states?
+
+**You answer, agent captures:**
+
+- State count
+- State definitions
+- Storyboard reference (if exists)
+- Visual specifications
+
+**Result:** Component file specification
+
+---
+
+## Step 3: Functional Logic (WHAT)
+
+**Agent asks:**
+
+1. What can users DO with this?
+2. What happens when they interact?
+3. Are there business rules?
+4. Does it need data from an API?
+5. Does it update other components?
+
+**You answer, agent captures:**
+
+- User actions
+- System responses
+- Business rules
+- API endpoints
+- Component sync
+
+**Result:** Feature file specification
+
+---
+
+## Example Dialogue
+
+See: [Coaching Dialogue Example](examples/coaching-dialogue.md)
+
+---
+
+## Output: Three Files
+
+**1. Page File**
+
+```markdown
+Pages/02-calendar-page.md
+
+**Component:** walk-slot-card.component.md
+**Feature:** walk-booking-logic.feature.md
+
+**Position:** Main content, full-width
+**Page-Specific Content:**
+
+- Header: "Familjen Svensson: Vecka 40"
+- Data: GET /api/families/:currentFamilyId/walks
+```
+
+**2. Component File**
+
+```markdown
+Components/walk-slot-card.component.md
+
+**Visual Specifications:**
+
+- 6 states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+- Typography, colors, spacing
+- Storyboard: Features/Storyboards/walk-states.jpg
+```
+
+**3. Feature File**
+
+```markdown
+Features/walk-booking-logic.feature.md
+
+**User Interactions:**
+
+- Book walk → GRAY state
+- Start walk → BLUE state
+
+**Business Rules:**
+
+- One active walk per dog
+- Can't book if slot taken
+
+**API Endpoints:**
+
+- POST /api/walks
+- PUT /api/walks/:id/start
+```
+
+---
+
+## Benefits
+
+- ✅ Clean handoffs (designer, developer, AI)
+- ✅ Nothing gets missed (all features documented)
+- ✅ Easy to maintain (update specs, not code)
+- ✅ Design system integrity (consistent patterns)
+
+---
+
+## Next Steps
+
+- [Examples](examples/) - See real decompositions
+- [Storyboards](02-storyboards/00-STORYBOARDS-GUIDE.md) - Visual documentation

package/src/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md

@@ -0,0 +1,312 @@
+# Page Specification Workflow
+
+**Step-by-step iterative decomposition from sketch to specs**
+
+---
+
+## Overview
+
+The agent guides you through specifying a page **from top to bottom**, one section at a time. You control the level of detail at each step.
+
+---
+
+## The Workflow
+
+### Step 1: Identify All Sections
+
+**Agent analyzes sketch and outputs:**
+
+```
+📋 Page Sections Detected:
+
+1. Navigation Header
+2. Hero Section
+3. Calendar Component
+4. Leaderboard Component
+5. Footer
+
+Does this match your sketch? Any sections missing or incorrectly identified?
+```
+
+**You respond:**
+
+- Confirm sections
+- Add missing sections
+- Rename sections
+- Reorder sections
+
+---
+
+### Step 2: Section Purpose
+
+**For each section, agent asks:**
+
+```
+📍 Section: Navigation Header
+
+What is the purpose of this section?
+- User navigation?
+- Branding?
+- User account access?
+- Search functionality?
+```
+
+**You respond:**
+
+```
+"User navigation and branding. Shows logo, main menu, and user profile."
+```
+
+**Agent captures:**
+
+```markdown
+## Navigation Header
+
+**Purpose:** User navigation and branding
+**Contains:** Logo, main menu, user profile
+```
+
+---
+
+### Step 3: List Objects in Section
+
+**Agent outputs:**
+
+```
+🔍 Objects in Navigation Header:
+
+1. Logo (image)
+2. Main Menu (navigation)
+3. User Profile (dropdown)
+
+Shall I specify each object, or is this section simple enough to keep schematic?
+```
+
+**You choose:**
+
+- **Option A:** "Specify each object" → Go deeper
+- **Option B:** "Keep schematic" → Move to next section
+
+---
+
+### Step 4: Decompose Containers
+
+**If object is a container, agent asks:**
+
+```
+📦 Main Menu (Container)
+
+What components does this contain?
+1. Home link
+2. Calendar link
+3. Leaderboard link
+4. Settings link
+
+Are these simple links, or do any need detailed specs?
+```
+
+**You respond:**
+
+```
+"Simple links, no detail needed"
+```
+
+**Agent captures:**
+
+```markdown
+### Main Menu
+
+- Home link
+- Calendar link
+- Leaderboard link
+- Settings link
+```
+
+---
+
+### Step 5: Specify Atomic Components
+
+**When reaching smallest parts:**
+
+```
+🔬 User Profile (Dropdown)
+
+This looks complex (multiple states, interactions).
+
+Should I:
+A) Create detailed Component + Feature files (3-tier)
+B) Keep simple specification in Page file
+C) Skip for now, mark as TODO
+```
+
+**You choose based on complexity:**
+
+- **Simple:** Keep in Page file
+- **Complex:** Decompose to 3 files
+- **Later:** Mark TODO
+
+---
+
+## Example: TaskFlow Calendar Page
+
+### Full Workflow
+
+**Step 1: Sections**
+
+```
+Agent: "I see 5 sections: Header, Week Overview, Leaderboard, Calendar, Footer"
+You: "Correct!"
+```
+
+**Step 2: Section Purposes**
+
+```
+Agent: "What's the purpose of Week Overview?"
+You: "Shows current week number and 7-day status circles"
+```
+
+**Step 3: Week Overview Objects**
+
+```
+Agent: "Objects detected:
+1. Week number label (text)
+2. 7 day circles (repeated component)
+
+Specify each or keep schematic?"
+You: "Specify the day circles, they have states"
+```
+
+**Step 4: Day Circle Component**
+
+```
+Agent: "Day circles look complex (3 states: empty, booked, completed).
+Should I create Component + Feature files?"
+You: "Yes, decompose it"
+```
+
+**Step 5: Calendar Section**
+
+```
+Agent: "Calendar has 6 walk states, countdown timers, business rules.
+This is highly complex. Should I:
+- Create 3-tier decomposition
+- Reference your storyboard (App-Main-Booking-States.jpg)"
+You: "Yes, decompose and reference storyboard"
+```
+
+---
+
+## Designer Control Points
+
+At each step, you decide:
+
+### Detail Level
+
+- **Schematic:** Just list components, no details
+- **Moderate:** Basic specs (size, position, content)
+- **Detailed:** Full 3-tier decomposition
+
+### When to Stop
+
+- **Good enough:** "This is clear, move on"
+- **Need detail:** "Let's specify this fully"
+- **Later:** "Mark as TODO, we'll come back"
+
+### Feedback Loop
+
+```
+Agent: "Here's what I captured for Navigation Header..."
+You: "Actually, the logo should be clickable and link to home"
+Agent: "Updated! Logo is now a link component."
+```
+
+---
+
+## Output Structure
+
+### Schematic Page Spec
+
+```markdown
+Pages/02-calendar-page.md
+
+## Navigation Header
+
+**Purpose:** User navigation and branding
+
+- Logo (clickable, links to home)
+- Main menu (4 links)
+- User profile dropdown
+
+## Calendar Section
+
+**Purpose:** Book and manage dog walks
+**Component:** → walk-slot-card.component.md
+**Feature:** → walk-booking-logic.feature.md
+**Storyboard:** → Features/Storyboards/walk-states.jpg
+```
+
+### Detailed Page Spec
+
+```markdown
+Pages/02-calendar-page.md
+
+## Navigation Header
+
+**Purpose:** User navigation and branding
+**Position:** Top, full-width, fixed
+**Height:** 64px
+
+### Logo
+
+**Component:** → logo.component.md
+**Position:** Left, 16px padding
+**Size:** 40x40px
+**Action:** Click → Navigate to home
+
+### Main Menu
+
+**Component:** → nav-menu.component.md
+**Position:** Center
+**Items:** Home, Calendar, Leaderboard, Settings
+
+### User Profile
+
+**Component:** → user-dropdown.component.md
+**Feature:** → user-menu-logic.feature.md
+**Position:** Right, 16px padding
+```
+
+---
+
+## Benefits
+
+✅ **Iterative:** Specify what you need, when you need it
+✅ **Flexible:** Control detail level per section
+✅ **Collaborative:** Agent asks, you decide
+✅ **Efficient:** Don't over-specify simple sections
+✅ **Complete:** Nothing gets missed
+✅ **Aligned:** Feedback loop at every step
+
+---
+
+## When to Use
+
+**Use this workflow when:**
+
+- Starting a new page specification
+- Converting a sketch to structured specs
+- Unsure how detailed to be
+- Want guided decomposition
+
+**Skip this workflow when:**
+
+- Page is extremely simple (1-2 sections)
+- You already know the structure
+- Rapid prototyping (schematic only)
+
+---
+
+## Next Steps
+
+- [Complexity Detection](01-complexity-detection.md) - When to decompose components
+- [Complexity Router Workflow](02-complexity-router-workflow.md) - How to decompose complex components

package/src/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md

@@ -0,0 +1,75 @@
+# Storyboard Integration
+
+**Using visual storyboards for complex components**
+
+---
+
+## Core Concepts (01-)
+
+### [What Are Storyboards?](01-what-are-storyboards.md)
+
+Visual documentation of state transitions and flows
+
+### [When to Use Storyboards](01-when-to-use.md)
+
+Complexity indicators that require visual documentation
+
+### [Storyboard Types](01-storyboard-types.md)
+
+State transitions, interaction flows, multi-component sync
+
+---
+
+## Storage & Organization (02-)
+
+### [File Structure](02-file-structure.md)
+
+Where to store storyboards in the three-tier architecture
+
+### [Naming Conventions](02-naming-conventions.md)
+
+How to name storyboard files
+
+---
+
+## Creation Guidelines
+
+### [How to Create Storyboards](creation-guide.md)
+
+Hand-drawn, digital, or annotated screenshots
+
+### [Annotation Best Practices](annotation-guide.md)
+
+Numbering, labels, and visual indicators
+
+---
+
+## Integration
+
+### [Referencing in Feature Files](feature-file-integration.md)
+
+How to link storyboards from specifications
+
+### [Referencing in Component Files](component-file-integration.md)
+
+Visual state references
+
+---
+
+## Examples
+
+### [TaskFlow Task States](examples/task-states.md)
+
+6-state walk booking storyboard
+
+### [Search Flow](examples/search-flow.md)
+
+Multi-step interaction storyboard
+
+---
+
+## Benefits
+
+### [Why Storyboards Work](benefits.md)
+
+Developer clarity, QA testing, design consistency

package/src/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md

@@ -0,0 +1,128 @@
+# Benefits of Three-Tier Architecture
+
+**Why this approach works**
+
+---
+
+## 1. Prevents Overwhelming Specs
+
+**Before:**
+
+- 800-line monolithic file
+- Everything mixed together
+- Hard to find anything
+
+**After:**
+
+- 3 focused files (100-200 lines each)
+- Clear separation
+- Easy to navigate
+
+---
+
+## 2. Clean Handoffs
+
+**Visual Designer** receives:
+
+- `Components/` folder only
+- Clear visual specifications
+- Creates Figma components
+
+**Developer** receives:
+
+- `Features/` folder only
+- Clear business logic
+- Implements functionality
+
+**You** maintain:
+
+- `Pages/` folder
+- Design system integrity
+- Page-specific content
+
+---
+
+## 3. Nothing Gets Missed
+
+**Problem:** Prototype missing leaderboard, week view wrong
+
+**Cause:** Monolithic spec, developer overwhelmed
+
+**Solution:**
+
+- Component file lists ALL visual elements
+- Feature file lists ALL interactions
+- Storyboard shows ALL states
+- **Nothing gets missed**
+
+---
+
+## 4. Easy to Update
+
+**Change request:** "Add countdown timers"
+
+**Before (Code):**
+
+- Regenerate code
+- Previous features break
+- 2+ hours fixing
+
+**After (Spec):**
+
+- Update Feature file (15 minutes)
+- Regenerate with full context
+- Everything works
+
+---
+
+## 5. Reusability
+
+**Same component, different pages:**
+
+```
+Pages/02-calendar-page.md ──┐
+Pages/05-dashboard.md ──────┼→ Components/calendar-widget.component.md
+Pages/08-mobile-view.md ────┘         ↓
+                                Features/calendar-logic.feature.md
+```
+
+Update Component or Feature once, all pages benefit.
+
+---
+
+## 6. Team Collaboration
+
+**UX Designers** → Focus on `Components/` (Figma specs)  
+**Developers** → Focus on `Features/` (logic implementation)  
+**Content Writers** → Focus on `Pages/` (translations)  
+**Product Managers** → Focus on `Features/` (business rules)
+
+Everyone works in parallel, no conflicts.
+
+---
+
+## 7. Design System Integrity
+
+**Page files** reference components:
+
+```markdown
+**Component:** button-primary.component.md
+```
+
+Ensures consistency across pages.
+
+Easy to update design system globally.
+
+---
+
+## ROI
+
+**Time saved per feature:** 2 hours  
+**Over 10 features:** 20 hours  
+**Over product lifecycle:** 100+ hours
+
+**Quality improvement:**
+
+- Zero missing features
+- Consistent design
+- Maintainable codebase