whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-12-functional-components/lesson-01-patterns-emerge.md

@@ -0,0 +1,263 @@
+# Module 12: Functional Components
+
+## Lesson 1: When Patterns Emerge
+
+**Identifying reusable elements across your specifications**
+
+---
+
+## The Natural Progression
+
+You've written specifications for multiple pages. And something happens:
+
+You're specifying a button on page 3... and realize it's identical to the button on page 1.
+
+Same states. Same behavior. Same styling. Different label.
+
+**A pattern has emerged.**
+
+---
+
+## Why Extract Functional Components?
+
+### Consistency
+
+Same Functional Component = same behavior everywhere.
+
+When the button on the signup form works like the button on the settings page, users don't have to relearn anything.
+
+### Efficiency
+
+Specify once, reference many times.
+
+Instead of copying the full button specification to every page, you define it once and reference it.
+
+### Maintainability
+
+Change once, update everywhere.
+
+Need to update the loading state? Change the component definition. Every instance inherits the update.
+
+### Communication
+
+Shared vocabulary with developers.
+
+"Use the primary Button component" is clearer than "make a blue button that does this specific thing."
+
+---
+
+## When to Extract
+
+Not everything should be a component. And **objects and spacing have different extraction timing:**
+
+### Objects: Extract on Second Use
+
+The first time a button or card appears, it's a one-off — it stays inline in the page spec. The second time the same pattern appears (same states, same behavior), it's a real pattern. Extract it to the design system.
+
+First use = one-off. Second use = pattern. Extract.
+
+### Spacing: Extract Immediately
+
+Spacing extracts on **first use** — no waiting for a second occurrence.
+
+Why? Because spacing is relational. When you decide that a heading needs `space-xl` above a card grid, that's a universal design principle — not a page-specific detail. It applies everywhere that pair of object types appears.
+
+### The Decision Checklist
+
+For objects, look for:
+
+**Appears more than once**
+
+Once is an instance. Twice or more is a pattern worth extracting.
+
+**Consistent behavior**
+
+The element behaves the same way everywhere. If behavior differs, they're different elements.
+
+**Worth centralizing**
+
+The extraction provides value. Sometimes inline is simpler.
+
+**Meaningful abstraction**
+
+"Button" is meaningful. "Blue rectangle with text" is not.
+
+---
+
+## What IS a Functional Component?
+
+A **Functional Component** is a reusable widget with defined functionality:
+
+- **Variants** — Different configurations (detailed, compact, minimal)
+- **States** — Behavioral states (loading, loaded, error, refreshing)
+- **Props** — Configurable options (location, maxResults, onSelect)
+- **Behavior** — What the widget does (fetches data, handles input, manages state)
+
+**Key distinction:** Functional Components are specification-level widgets, not implementation-level UI components (React, Vue, etc.).
+
+### Examples
+
+| Functional Component | What It Does |
+|---------------------|--------------|
+| Weather Widget | Fetches weather, displays forecast, handles location, refresh |
+| Search Widget | Accepts input, fetches suggestions, handles selection, keyboard nav |
+| Login Form | Validates fields, manages auth flow, handles errors |
+| Comment Section | Manages comment input, character count, submission, validation |
+| Task Card | Displays task, handles status changes, actions, completion |
+
+---
+
+## What Is NOT a Functional Component
+
+Not everything needs extraction:
+
+| Functional Component | NOT a Functional Component |
+|---------------------|---------------------------|
+| Weather Widget | A single temperature display |
+| Search Widget | A single input field |
+| Login Form | A single button |
+| Task Card | A checkbox element |
+| Comment Section | A color value or margin |
+
+**Functional Components have functionality and behavior.** Simple elements and styles don't.
+
+If the thing doesn't have complex behavior, states, and reusable functionality, it's probably just an element or style token, not a Functional Component.
+
+---
+
+## Functional Component vs. Instance
+
+**Functional Component:** The widget definition
+
+```markdown
+## Weather Widget (Functional Component)
+Variants: compact, detailed, minimal
+States: loading, loaded, error, refreshing
+Props: location, variant, autoRefresh, units
+```
+
+**Instance:** A specific usage
+
+```markdown
+### Homepage Hero Weather
+- Functional Component: Weather Widget
+- Variant: detailed
+- Location: User's city
+- AutoRefresh: true
+- OnLoad: Fetch forecast data
+```
+
+The Functional Component defines the possibilities. The instance applies them.
+
+---
+
+## The Extraction Process
+
+When you notice a pattern:
+
+### 1. Identify the Pattern
+
+"This button appears in signup, settings, and checkout..."
+
+### 2. Document the Variations
+
+- Primary (blue, white text)
+- Secondary (white, blue border)
+- Ghost (transparent, text only)
+
+### 3. List All States
+
+- Default
+- Hover
+- Active
+- Loading
+- Disabled
+
+### 4. Define the Props
+
+| Prop | Type | Default | Options |
+|------|------|---------|---------|
+| variant | string | primary | primary, secondary, ghost |
+| size | string | md | sm, md, lg |
+| disabled | boolean | false | |
+
+### 5. Create the Component Document
+
+Goes in `C-UX-Scenarios/Functional-Components/weather-widget.md`
+
+### 6. Update Page Specs
+
+Replace inline definitions with component references.
+
+### Visual Extraction Flow
+
+```
+STEP 1: IDENTIFY PATTERN
+┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
+│  Signup Page     │   │  Settings Page   │   │  Checkout Page   │
+├──────────────────┤   ├──────────────────┤   ├──────────────────┤
+│ Button (primary) │   │ Button (primary) │   │ Button (primary) │
+│ States: default, │   │ States: default, │   │ States: default, │
+│  hover, loading  │   │  hover, loading  │   │  hover, loading  │
+└──────────────────┘   └──────────────────┘   └──────────────────┘
+        ↓                      ↓                      ↓
+        └──────────────────────┴──────────────────────┘
+                              ↓
+                   PATTERN RECOGNIZED
+                              ↓
+
+STEP 2-4: DOCUMENT COMPONENT
+┌────────────────────────────────────────────────────────────┐
+│ C-UX-Scenarios/Functional-Components/weather-widget.md                       │
+├────────────────────────────────────────────────────────────┤
+│ Variants: primary, secondary, ghost                        │
+│ States: default, hover, active, loading, disabled          │
+│ Props: variant, size, disabled, loading                    │
+└────────────────────────────────────────────────────────────┘
+                              ↓
+
+STEP 5-6: UPDATE PAGE SPECS
+┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
+│  Signup Page     │   │  Settings Page   │   │  Checkout Page   │
+├──────────────────┤   ├──────────────────┤   ├──────────────────┤
+│ Component:       │   │ Component:       │   │ Component:       │
+│   Button         │   │   Button         │   │   Button         │
+│   (primary, lg)  │   │   (primary, md)  │   │   (primary, lg)  │
+│ Label: "Sign Up" │   │ Label: "Save"    │   │ Label: "Pay Now" │
+└──────────────────┘   └──────────────────┘   └──────────────────┘
+        ↑                      ↑                      ↑
+        └──────────────────────┴──────────────────────┘
+                              ↑
+                 ALL REFERENCE SAME DEFINITION
+```
+
+---
+
+## Design System
+
+How you handle components depends on your mode:
+
+| Mode | Component Handling |
+|------|-------------------|
+| **None** | Keep inline in page specs |
+| **Building** | Extract to C-UX-Scenarios/Functional-Components/ |
+| **Library** | Reference external (shadcn, etc.) |
+| **Existing** | Import from previous project |
+
+If you're in Mode 1 (None), you can still document patterns — just keep them inline rather than extracting to separate files.
+
+---
+
+## What's Next
+
+In the next lesson, you'll learn the component anatomy in detail — how to document variants, states, props, and usage rules.
+
+---
+
+**[Continue to Lesson 2: Component Anatomy →](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-12-functional-components/lesson-02-component-anatomy.md

@@ -0,0 +1,332 @@
+# Module 12: Functional Components
+
+## Lesson 2: Functional Component Anatomy
+
+**How to document Functional Components completely**
+
+---
+
+## The Functional Component Template
+
+Every Functional Component follows this structure:
+
+```markdown
+## [Component Name]
+
+### Description
+What this Functional Component is and when to use it.
+
+### Variants
+Different visual styles.
+
+### States
+Behavioral states.
+
+### Props
+Configurable options.
+
+### Usage Rules
+When and how to use it correctly.
+
+### Accessibility
+Keyboard, screen reader, and focus requirements.
+```
+
+### Component Structure Visualized
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                FUNCTIONAL COMPONENT DEFINITION                │
+│      (weather-widget.md in C-UX-Scenarios/Functional-Components/)  │
+└──────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ↓                     ↓                     ↓
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ WHAT         │    │ HOW          │    │ WHEN         │
+│ Description  │    │ Variants     │    │ Usage Rules  │
+│              │    │ States       │    │              │
+│ Purpose &    │    │ Props        │    │ DO/DON'T     │
+│ use cases    │    │              │    │ guidelines   │
+└──────────────┘    └──────────────┘    └──────────────┘
+        │                     │                     │
+        └─────────────────────┼─────────────────────┘
+                              │
+                              ↓
+                    ┌──────────────────┐
+                    │ WHO              │
+                    │ Accessibility    │
+                    │                  │
+                    │ Screen readers,  │
+                    │ keyboard, ARIA   │
+                    └──────────────────┘
+                              │
+                              ↓
+        ╔═══════════════════════════════════════════╗
+        ║      COMPLETE FUNCTIONAL COMPONENT        ║
+        ║                                           ║
+        ║  Ready to be referenced by page specs    ║
+        ║  All behavior defined, no ambiguity      ║
+        ╚═══════════════════════════════════════════╝
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        ↓                     ↓                     ↓
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ Page 1       │    │ Page 2       │    │ Page 3       │
+│ Instance A   │    │ Instance B   │    │ Instance C   │
+│              │    │              │    │              │
+│ Button       │    │ Button       │    │ Button       │
+│ (primary,lg) │    │ (secondary)  │    │ (primary,md) │
+└──────────────┘    └──────────────┘    └──────────────┘
+```
+
+**Each section serves a purpose:** Description explains WHY, Variants/States/Props explain HOW, Usage Rules explain WHEN, Accessibility explains WHO can use it.
+
+---
+
+## Section: Description
+
+One paragraph explaining what the Functional Component is and its purpose.
+
+```markdown
+### Description
+Primary action trigger used throughout the application.
+Communicates importance through visual weight and draws
+user attention to key actions.
+```
+
+Keep it concise. This is the "why this exists" summary.
+
+---
+
+## Section: Variants
+
+Different visual styles for different purposes.
+
+```markdown
+### Variants
+
+| Variant | Use Case | Visual |
+|---------|----------|--------|
+| Primary | Main action on page | Blue bg, white text |
+| Secondary | Alternative action | White bg, blue border |
+| Ghost | Tertiary action | Transparent, text only |
+| Danger | Destructive action | Red bg, white text |
+```
+
+**Rule:** One primary action per screen. Everything else is secondary or lower.
+
+---
+
+## Section: States
+
+How the Functional Component looks in different conditions.
+
+```markdown
+### States
+
+| State | Trigger | Visual Change |
+|-------|---------|---------------|
+| Default | Initial load | Standard appearance |
+| Hover | Mouse over | Slight darkening, shadow |
+| Active | Mouse down | Pressed appearance (scale 98%) |
+| Focused | Keyboard focus | Blue outline, 2px offset |
+| Disabled | disabled=true | Grayed out, no interactions |
+| Loading | loading=true | Spinner replaces text |
+```
+
+Include the trigger (what causes this state) and the visual change.
+
+---
+
+## Section: Props
+
+Configurable options for instances.
+
+```markdown
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | string | "primary" | Visual style: primary, secondary, ghost, danger |
+| size | string | "md" | Size: sm (32px), md (40px), lg (48px) |
+| disabled | boolean | false | Disables interaction |
+| loading | boolean | false | Shows loading spinner |
+| icon | node | null | Optional leading icon |
+| iconPosition | string | "left" | Icon position: left, right |
+| fullWidth | boolean | false | Spans full container width |
+| type | string | "button" | HTML type: button, submit, reset |
+```
+
+**Important:** Specify the exact values, not just the types.
+
+---
+
+## Section: Usage Rules
+
+When and how to use the Functional Component correctly.
+
+```markdown
+### Usage Rules
+
+**DO:**
+- Use primary variant for the main action on each screen
+- Always include text label (icon optional)
+- Ensure minimum touch target of 44px
+- Use loading state during async operations
+- Position primary action prominently
+
+**DON'T:**
+- Use multiple primary buttons on one screen
+- Use icon-only buttons without aria-label
+- Disable buttons without explanation
+- Use ghost variant for primary actions
+- Mix variants in a single button group
+```
+
+These rules prevent misuse.
+
+---
+
+## Section: Accessibility
+
+Requirements for keyboard, screen reader, and focus management.
+
+```markdown
+### Accessibility
+
+**Semantic:**
+- Element: `<button>` (or `<a>` if navigating)
+- Role: Implicit from element
+
+**Keyboard:**
+- Focusable: Yes (when not disabled)
+- Activation: Enter or Space
+- Focus visible: 2px blue outline with 2px offset
+
+**Screen Reader:**
+- Announces: "[label], button"
+- Loading: aria-busy="true", announce "Loading"
+- Disabled: aria-disabled="true", announce "disabled"
+
+**ARIA (when needed):**
+- Icon-only: aria-label="[action description]"
+- Opens dialog: aria-haspopup="dialog"
+- Expanded state: aria-expanded="true/false"
+```
+
+---
+
+## Complete Example: Button Component
+
+```markdown
+# Button Component
+
+## Description
+Primary action trigger used throughout the application.
+Communicates importance through visual weight and guides
+users toward key actions.
+
+## Variants
+
+| Variant | Use Case | Visual |
+|---------|----------|--------|
+| Primary | Main page action | Blue bg (#0066FF), white text |
+| Secondary | Alternative action | White bg, blue border |
+| Ghost | Tertiary/inline action | Transparent, blue text |
+| Danger | Destructive action | Red bg (#DC2626), white text |
+
+## States
+
+| State | Trigger | Visual |
+|-------|---------|--------|
+| Default | Initial | Standard appearance |
+| Hover | Mouse over | 10% darker, subtle shadow |
+| Active | Mouse down | Scale 98%, darker still |
+| Focused | Keyboard | Blue 2px outline |
+| Disabled | prop | 50% opacity, cursor not-allowed |
+| Loading | prop | Spinner replaces text |
+
+## Props
+
+| Prop | Type | Default | Options |
+|------|------|---------|---------|
+| variant | string | "primary" | primary, secondary, ghost, danger |
+| size | string | "md" | sm (32px), md (40px), lg (48px) |
+| disabled | boolean | false | |
+| loading | boolean | false | |
+| icon | node | null | Any icon Functional Component |
+| iconPosition | string | "left" | left, right |
+| fullWidth | boolean | false | |
+
+## Usage Rules
+
+**One primary per screen.** Secondary and ghost for other actions.
+
+**Always has text.** Icon-only requires aria-label.
+
+**Loading replaces text.** Button stays same size.
+
+**Touch target: 44px minimum.** Even if visually smaller.
+
+## Accessibility
+
+- Element: `<button type="button">`
+- Keyboard: Enter/Space activates
+- Focus: Visible blue outline
+- Loading: aria-busy="true"
+- Disabled: aria-disabled="true"
+- Icon-only: aria-label required
+```
+
+---
+
+## The Freya Method
+
+Freya notices patterns as you specify:
+
+> "This is the third time you've specified a card with image, title, and description. Should we extract it as a Functional Component?"
+
+> "Your submit buttons are inconsistent — some say 'Submit', others say 'Save'. Should we standardize?"
+
+She helps you see what's becoming a pattern before you realize it.
+
+---
+
+## File Organization
+
+```
+C-UX-Scenarios/Functional-Components/
+├── Functional Components/
+│   ├── button.md
+│   ├── input.md
+│   ├── card.md
+│   ├── modal.md
+│   └── toast.md
+├── tokens/
+│   ├── colors.yaml
+│   ├── typography.yaml
+│   └── spacing.yaml
+└── patterns/
+    ├── form-layout.md
+    └── page-structure.md
+```
+
+Components go in `Functional Components/`. Design tokens (colors, fonts, spacing) go in `tokens/`.
+
+---
+
+## What's Next
+
+In the tutorial, you'll identify Functional Components from your existing specifications and document them using this anatomy.
+
+---
+
+**[Continue to Tutorial: Extract Your Components →](tutorial-12.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-patterns-emerge.md) | [Back to Module Overview](module-12-functional-components-overview.md)
+
+*Part of Module 12: Functional Components*