whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-12-functional-components/tutorial-12.md

@@ -0,0 +1,405 @@
+# Tutorial 12: Extract Your Components
+
+**Hands-on guide to identifying and documenting reusable patterns**
+
+---
+
+## Overview
+
+This tutorial walks you through identifying reusable patterns in your specifications and documenting them as components.
+
+**Time:** 30-40 minutes
+**Prerequisites:** Page specifications completed (Module 11)
+**Agent:** Freya
+**What you'll create:** Component documentation in `C-UX-Scenarios/Functional-Components/`
+
+---
+
+## Before You Start
+
+**You'll need:**
+
+- Your completed page specifications
+- Understanding of common UI patterns
+- Your Design System mode (None, Building, Library, Existing)
+
+**Note on modes:**
+
+- **Mode 1 (None):** You can still identify patterns but keep them inline
+- **Mode 2 (Building):** Extract components to separate files
+- **Mode 3 (Library):** Reference external library components
+- **Mode 4 (Existing):** Import and extend from previous project
+
+---
+
+## Step 1: Identify Repeated Patterns (10 min)
+
+### Ask Freya to scan your specs:
+
+**You say:**
+> "Review my page specifications and identify elements that appear 2 or more times. Which patterns should we consider extracting as components?"
+
+**Freya analyzes:**
+> "Scanning your specifications... I found these repeated patterns:
+>
+> **Buttons (7 occurrences)**
+> - Signup submit, Login submit, Settings save, Profile update...
+> - Variants: primary (5), secondary (2)
+> - States: loading appears 4 times
+>
+> **Input Fields (12 occurrences)**
+> - Email (3), Password (2), Text (7)
+> - Validation patterns consistent
+>
+> **Cards (4 occurrences)**
+> - Task cards, Profile card, Summary cards
+> - Structure: image + title + description
+>
+> Recommend starting with Button — highest usage, clear patterns."
+
+### Pattern Discovery Visualization
+
+```
+FREYA'S ANALYSIS: Scanning Page Specifications
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│ P01-landing │  │ P02-signup  │  │ P03-settings│  │ P04-profile │
+└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
+      ↓                ↓                ↓                ↓
+      └────────────────┴────────────────┴────────────────┘
+                              ↓
+                    PATTERN DETECTION
+                              ↓
+        ┌─────────────────────┼─────────────────────┐
+        ↓                     ↓                     ↓
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ Button       │    │ Input        │    │ Card         │
+│ 7 instances  │    │ 12 instances │    │ 4 instances  │
+├──────────────┤    ├──────────────┤    ├──────────────┤
+│ ✓ Primary(5) │    │ ✓ Email(3)   │    │ ✓ Task cards │
+│ ✓ Second.(2) │    │ ✓ Password(2)│    │ ✓ Profile    │
+│ ✓ Loading(4) │    │ ✓ Text(7)    │    │ ✓ Summary    │
+└──────────────┘    └──────────────┘    └──────────────┘
+   HIGH PRIORITY       HIGH PRIORITY       MED PRIORITY
+        ↓
+  START HERE (most used, clearest pattern)
+```
+
+---
+
+## Step 2: Document First Component (10 min)
+
+### Start with Button:
+
+**Freya:**
+> "Let's document the Button component. First, what variants have you used across your specs?"
+
+**You respond:**
+> "Primary for main actions, secondary for alternatives. I also used a ghost style for inline actions."
+
+**Freya continues:**
+> "And what states appear in your storyboards?"
+
+**You respond:**
+> "Default, hover, active, loading, disabled. The loading state shows a spinner."
+
+**Freya builds the component:**
+
+```markdown
+# Button Component
+
+## Description
+Action trigger used throughout the application.
+Communicates importance through visual hierarchy.
+
+## Variants
+| Variant | Use Case |
+|---------|----------|
+| Primary | Main action per screen |
+| Secondary | Alternative actions |
+| Ghost | Inline/tertiary actions |
+
+## States
+| State | Trigger | Behavior |
+|-------|---------|----------|
+| Default | Initial | Standard appearance |
+| Hover | Mouse over | Darkens 10% |
+| Active | Mouse down | Scale 98% |
+| Loading | loading=true | Spinner, disabled |
+| Disabled | disabled=true | 50% opacity |
+
+## Props
+| Prop | Type | Default |
+|------|------|---------|
+| variant | string | "primary" |
+| size | string | "md" |
+| loading | boolean | false |
+| disabled | boolean | false |
+| fullWidth | boolean | false |
+```
+
+### Add usage rules:
+
+**Freya:**
+> "Based on your specs, what usage rules should we document?"
+
+**You respond:**
+> "One primary per screen. Always has text label. Loading replaces text but keeps width."
+
+**Freya adds:**
+```markdown
+## Usage Rules
+- One primary button per screen
+- Always include text label
+- Loading state: spinner replaces text, width unchanged
+- Minimum touch target: 44px
+```
+
+---
+
+## Step 3: Continue with Other Components (10 min)
+
+### Move to Input:
+
+**Freya:**
+> "Button is complete. Next, let's document Input. What types have you used?"
+
+**You respond:**
+> "Text, email, password. Password has the show/hide toggle."
+
+**Work through:**
+- Types: text, email, password
+- States: default, focus, filled, error, disabled
+- Features: validation, error messages, helper text
+
+**Freya documents:**
+```markdown
+# Input Component
+
+## Description
+Text entry field with validation and error handling.
+
+## Types
+| Type | Features |
+|------|----------|
+| text | Standard input |
+| email | Email validation |
+| password | Masked, show/hide toggle |
+
+## States
+| State | Visual |
+|-------|--------|
+| Default | Gray border |
+| Focus | Blue border |
+| Filled | Content visible |
+| Error | Red border, error message |
+| Disabled | Grayed out |
+
+## Props
+| Prop | Type | Description |
+|------|------|-------------|
+| type | string | text, email, password |
+| label | string | Above field |
+| placeholder | string | In field when empty |
+| error | string | Error message |
+| required | boolean | Required indicator |
+```
+
+### Repeat for Card and other patterns...
+
+---
+
+## Step 4: Update Page Specifications (5 min)
+
+### Replace inline definitions with references:
+
+**Before (inline):**
+```markdown
+### Submit Button
+- Type: Button
+- Style: Primary, blue background, white text
+- States: Default, Hover, Active, Loading, Disabled
+- Label: "Create Account"
+- Loading: Shows spinner
+- OnClick: Submit form
+```
+
+**After (reference):**
+```markdown
+### Submit Button
+- Component: Button (primary, lg)
+- Label: "Create Account"
+- OnClick: Submit form
+- See: [Button Component](../../C-UX-Scenarios/Functional-Components/button.md)
+```
+
+The component definition handles the states and styling. The page spec only needs to specify what's unique to this instance.
+
+### Transformation Visualization
+
+```
+BEFORE: Inline Specifications (Repetitive)
+┌──────────────────────────────────────────────────────────────┐
+│ P02-signup-page/specification.md                             │
+├──────────────────────────────────────────────────────────────┤
+│ Submit Button:                                               │
+│ - Type: Button                                               │
+│ - Style: Primary, blue background, white text                │
+│ - States: Default, Hover, Active, Loading, Disabled          │
+│ - Hover: Darkens 10%, subtle shadow                          │
+│ - Loading: Spinner replaces text                             │
+│ - Disabled: 50% opacity, cursor not-allowed                  │
+│ - Accessibility: role=button, keyboard navigation            │
+│ - Label: "Create Account"                                    │
+│ - OnClick: Submit form                                       │
+│                                                              │
+│ 9 lines of specification (7 are repeated elsewhere)         │
+└──────────────────────────────────────────────────────────────┘
+                              ↓
+                    EXTRACT TO COMPONENT
+                              ↓
+┌──────────────────────────────────────────────────────────────┐
+│ C-UX-Scenarios/Functional-Components/button.md                         │
+├──────────────────────────────────────────────────────────────┤
+│ All variants, states, props, rules, accessibility defined    │
+│ (Single source of truth for all buttons)                     │
+└──────────────────────────────────────────────────────────────┘
+                              ↓
+AFTER: Component References (Concise)
+┌──────────────────────────────────────────────────────────────┐
+│ P02-signup-page/specification.md                             │
+├──────────────────────────────────────────────────────────────┤
+│ Submit Button:                                               │
+│ - Component: Button (primary, lg)                            │
+│ - Label: "Create Account"                                    │
+│ - OnClick: Submit form                                       │
+│                                                              │
+│ 4 lines of specification (only instance-specific details)   │
+│ All behavior inherited from Button component ✓               │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Result:** 9 lines → 4 lines. Clearer, more maintainable, single source of truth.
+
+---
+
+## Step 5: Verify Consistency (5 min)
+
+### Check for inconsistencies:
+
+**Freya:**
+> "Let me check your specs for consistency against the new components..."
+
+> "Found 2 issues:
+> 1. P03-settings uses 'Cancel' as secondary button, but P02-signup uses 'Back' — should terminology be consistent?
+> 2. P04-profile has a button without specified variant — which should it be?"
+
+**Resolve:**
+> "Back for navigation, Cancel for canceling an action. The profile button should be primary."
+
+**Freya updates the specs accordingly.**
+
+---
+
+## Step 6: Save Component Documentation (2 min)
+
+### Organize files:
+
+```
+C-UX-Scenarios/Functional-Components/
+└── components/
+    ├── button.md
+    ├── input.md
+    ├── card.md
+    └── ...
+```
+
+### Update component index:
+
+```markdown
+# Component Library
+
+## Core Components
+- [Button](components/button.md) - Action triggers
+- [Input](components/input.md) - Text entry
+- [Card](components/card.md) - Content containers
+
+## Status
+| Component | Status | Usage |
+|-----------|--------|-------|
+| Button | Complete | 7 instances |
+| Input | Complete | 12 instances |
+| Card | Complete | 4 instances |
+```
+
+---
+
+## What You've Created
+
+### Component documentation with:
+
+- Description and purpose
+- Variants for different use cases
+- States with triggers and visuals
+- Props with types and defaults
+- Usage rules
+- Accessibility requirements
+
+### Updated page specifications:
+
+- Reference components instead of inline definitions
+- Only specify instance-specific details
+- Consistent terminology
+
+---
+
+## Tips for Success
+
+**DO:**
+
+- Wait for 2+ usages before extracting
+- Keep components generic enough to reuse
+- Document usage rules clearly
+- Update all page specs to reference components
+
+**DON'T:**
+
+- Extract everything
+- Make components too specific
+- Forget to document states
+- Leave page specs with outdated inline definitions
+
+---
+
+## Common Questions
+
+**Q: What if a component has a unique state in one place?**
+A: Document it as a variant or extension. Or question whether it's really the same component.
+
+**Q: Should I extract a pattern that's only used once?**
+A: No. Wait for the second usage. Once is an instance, twice or more is a pattern.
+
+**Q: What about third-party library components (Mode 3)?**
+A: Document your customizations and token overrides, not the full component spec.
+
+---
+
+## You've Completed Module 12!
+
+**Your reusable patterns are documented.** You have:
+- Components extracted from specifications
+- Consistent terminology across pages
+- A foundation for design system growth
+
+---
+
+## Next Module
+
+**[Module 13: Design System →](../module-13-design-system/module-13-design-system-overview.md)**
+
+Choose your design system approach.
+
+---
+
+[← Back to Lesson 2](lesson-02-component-anatomy.md) | [Back to Module Overview](module-12-functional-components-overview.md)
+
+*Part of Module 12: Functional Components*

package/docs/learn/module-13-design-system/lesson-01-understanding-modes.md

@@ -0,0 +1,274 @@
+# Module 13: Design System
+
+## Lesson 1: Understanding the Four Modes
+
+**How component management affects your workflow**
+
+---
+
+## What Are Design System?
+
+When you set up WDS, you chose a mode for handling design components.
+
+This choice affects:
+- How Freya works with you
+- Where components are documented
+- How visuals are generated
+- What you deliver to developers
+
+---
+
+## The Four Modes
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| **1. None** | No design system | Quick projects, one-offs |
+| **2. Building** | System grows from work | First project for client |
+| **3. Library** | External library + tokens | Using shadcn/Radix/MUI |
+| **4. Existing** | Import from previous | Second+ project, same client |
+
+Each mode has different implications for how you work.
+
+---
+
+## Mode 1: None
+
+### What It Means
+
+No formal design system. Styling is ad-hoc.
+
+### How Freya Works
+
+- Styles defined inline in page specifications
+- No component extraction
+- Each element is self-contained
+
+### Example
+
+```markdown
+### Submit Button
+- Type: Button
+- Style: Blue background (#0066FF), white text, 14px rounded
+- States: Default, Hover (darker), Loading (spinner), Disabled (gray)
+- Label: "Create Free Account"
+```
+
+Everything is specified inline. No separate component document.
+
+### Best For
+
+- Landing pages
+- Quick prototypes
+- One-time projects
+- Tight deadlines
+
+### Trade-off
+
+Consistency is manual. If you want the same button elsewhere, you copy-paste.
+
+---
+
+## Mode 2: Building
+
+### What It Means
+
+Design system grows organically from your work.
+
+As you design, patterns emerge. When they appear 3+ times, you extract them as components.
+
+### How Freya Works
+
+She notices patterns:
+
+> "This button appears in three specifications. Should we extract it as a component?"
+
+You say yes → Goes into `C-UX-Scenarios/Functional-Components/`
+
+### Example
+
+After extraction:
+
+```markdown
+### Submit Button
+- Component: Button (primary, lg)
+- Label: "Create Free Account"
+```
+
+The component definition lives separately. Page specs reference it.
+
+### The Evolution
+
+```
+Project 1: Mode 2 (Building)
+    ↓
+You create components
+    ↓
+Project 2: Mode 4 (Existing)
+    ↓
+You reuse what you built
+```
+
+Your work compounds. Each project builds on the last.
+
+### Best For
+
+- First project for new client
+- Greenfield products
+- When brand is still forming
+
+---
+
+## Mode 3: Component Library
+
+### What It Means
+
+Using an external library (shadcn, Radix, MUI, etc.) with your branding.
+
+The library provides base components. You apply your tokens on top.
+
+### How Freya Works
+
+She references library components:
+
+> "This matches shadcn's Button component. Use the default variant with primary color?"
+
+### Example
+
+```markdown
+### Submit Button
+- Component: shadcn/Button
+- Variant: default
+- Size: lg
+- Class: Custom styles from tokens
+- Label: "Create Free Account"
+```
+
+```yaml
+# tokens/colors.yaml - Your brand applied to library
+colors:
+  primary: "#0066FF"  # Your blue
+  destructive: "#DC2626"  # Your red
+```
+
+### Best For
+
+- Speed to market
+- Consistent base components
+- Teams familiar with the library
+- When you don't need custom patterns
+
+### Trade-off
+
+You get the library's patterns, not your own. Customization has limits.
+
+---
+
+## Mode 4: Existing
+
+### What It Means
+
+Import design system from a previous project.
+
+You've built components before. Now you reuse them.
+
+### How Freya Works
+
+She loads your existing components:
+
+> "You have a Button component from the Acme project. Use it here?"
+
+You can extend with new variants:
+
+```markdown
+### Submit Button
+- Component: Button
+- Variant: "outline" (NEW)
+```
+
+### Best For
+
+- Second+ project for same client
+- Product families
+- Brand consistency across projects
+
+### The Power
+
+Your work compounds. Each project starts with a foundation.
+
+---
+
+## Mode Selection Flow
+
+```
+New Project Setup
+        ↓
+Do you need reusable components?
+        ↓
+    No → Mode 1: None
+        ↓
+    Yes → Do you have an existing system?
+              ↓
+          Yes → Mode 4: Existing
+              ↓
+          No → External library or custom?
+                    ↓
+                External → Mode 3: Library
+                    ↓
+                Custom → Mode 2: Building
+```
+
+---
+
+## Changing Modes
+
+You can upgrade modes as projects evolve:
+
+**Mode 1 → Mode 2**
+
+Start with no system, extract components as patterns emerge.
+
+**Mode 2 → Mode 4**
+
+Complete first project, import system to second project.
+
+**Mode 3 → Mode 2**
+
+Start with library, add custom components as needs grow.
+
+---
+
+## What Each Mode Creates
+
+| Mode | Output |
+|------|--------|
+| None | Inline styles only |
+| Building | `D-Design-System/` folder grows |
+| Library | `D-Design-System/tokens/` only |
+| Existing | `D-Design-System/` extended |
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Building when Library works | Evaluate existing options first |
+| None when project will grow | Anticipate future needs |
+| Existing when brand changed | Start fresh with Building |
+| Over-engineering early | Start None, upgrade later |
+
+---
+
+## What's Next
+
+Understanding your mode helps you work with Freya effectively. In the tutorial, you'll review your mode choice and ensure you're using it correctly.
+
+---
+
+**[Continue to Tutorial: Apply Your Mode →](tutorial-13.md)**
+
+---
+
+[← Back to Module Overview](module-13-design-system-overview.md)
+
+*Part of Module 13: Design System*