whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-10-storyboarding/lesson-02-storyboard-format.md

@@ -0,0 +1,410 @@
+# Module 10: Storyboarding
+
+## Lesson 2: Storyboard Format
+
+**How to document transformations clearly**
+
+---
+
+## The Structure
+
+Every storyboard follows this pattern:
+
+1. **Element name** — What's being storyboarded
+2. **Keyframes** — Each distinct state
+3. **Transitions** — What triggers the change
+4. **Why** — Purpose of each state
+5. **Timing** — Duration where relevant
+
+```
+Storyboard Anatomy:
+
+┌────────────────────────────────────────────────────────────┐
+│ ## [Element Name] Storyboard ◄─── 1. What's being tracked │
+├────────────────────────────────────────────────────────────┤
+│                                                            │
+│ ### Keyframe 0: Default State  ◄──── 2. Each distinct     │
+│ [Visual representation]                  state            │
+│ - State description                                        │
+│ - Key elements                                             │
+│                                                            │
+│ **Transition:** User clicks  ◄────── 3. What triggers      │
+│ **Why:** User needs feedback          change              │
+│                                                            │
+│ ### Keyframe 1: Loading State                             │
+│ [Visual representation]                                    │
+│ - What changed                                             │
+│ **Duration:** 300ms  ◄───────────── 5. Timing where       │
+│ **Why:** Prevents confusion             relevant          │
+│                                                            │
+└────────────────────────────────────────────────────────────┘
+                          ▲
+                    4. Purpose of each state
+```
+
+---
+
+## Basic Format
+
+```markdown
+## [Element Name] Storyboard
+
+### Keyframe 0: Default State
+[Image/description]
+- State description
+- Key visual elements
+- What user can interact with
+
+**Transition:** [What triggers next keyframe]
+
+### Keyframe 1: [State Name]
+[Image/description]
+- What changed
+- What's visible now
+- What user can do
+
+**Transition:** [What triggers next keyframe]
+
+### Keyframe 2: [State Name]
+...
+```
+
+---
+
+## Detailed Example: Form Submit Flow
+
+**Visual Overview:**
+
+```
+K0: Ready          K1: Submitting     K2: Success        K3: Error (alt)
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│ Email       │   │ Email       │   │ Email       │   │ Email       │
+│ ┌─────────┐ │   │ ┌─────────┐ │   │ ┌─────────┐ │   │ ┌─────────┐ │
+│ │email@...│ │   │ │email@...│ │   │ │email@...│ │   │ │email@...│ │ ⚠
+│ └─────────┘ │   │ └─────────┘ │   │ └─────────┘ │   │ └─────────┘ │
+│             │   │             │   │             │   │ ┌─────────┐ │
+│ Password    │   │ Password    │   │ Password    │   │ │Email    │ │
+│ ┌─────────┐ │   │ ┌─────────┐ │   │ ┌─────────┐ │   │ │exists!  │ │
+│ │•••••••••│ │   │ │•••••••••│ │   │ │•••••••••│ │   │ └─────────┘ │
+│ └─────────┘ │   │ └─────────┘ │   │ └─────────┘ │   │ Password    │
+│             │   │             │   │             │   │ ┌─────────┐ │
+│ ┌─────────┐ │   │ ┌─────────┐ │   │ ┌─────────┐ │   │ │•••••••••│ │
+│ │ Submit  │ │   │ │   ...   │ │   │ │   ✓     │ │   │ └─────────┘ │
+│ └─────────┘ │   │ └─────────┘ │   │ └─────────┘ │   │             │
+└─────────────┘   └─────────────┘   │ Account     │   │ ┌─────────┐ │
+                                    │ created!    │   │ │ Submit  │ │
+  User clicks       Processing       └─────────────┘   │ └─────────┘ │
+                    (300ms delay)    Success           └─────────────┘
+                                     (1.5s, redirect)   Error state
+```
+
+**Documented Format:**
+
+```markdown
+## Form Submit Storyboard
+
+### Keyframe 0: Default State (Ready to Submit)
+[Image: form-ready.png]
+- Form filled with valid data
+- Submit button: "Create Account" (enabled)
+- No loading indicators visible
+
+**Why:** User has completed form, ready to submit
+
+### Keyframe 1: Submitting State
+[Image: form-submitting.png]
+- Submit button shows spinner (text replaced)
+- Button disabled (grayed out)
+- Form fields locked (can't edit)
+**Transition:** User clicks submit (appears after 300ms delay)
+**Duration:** Until server responds
+
+**Why:** User knows request is processing, prevents double-submit
+
+### Keyframe 2: Success State
+[Image: form-success.png]
+- Submit button shows checkmark icon
+- Button background: Green
+- Success message appears above form: "Account created!"
+**Transition:** Server responds successfully
+**Duration:** 1.5s visible, then redirect
+
+**Why:** Confirms success before navigation
+
+### Keyframe 3: Error State
+[Image: form-error.png]
+- Submit button returns to default "Create Account"
+- Error banner appears at top: "Email already exists"
+- Email field highlighted in red
+- Form re-enabled for corrections
+**Transition:** Server responds with error
+
+**Why:** User can identify and fix the problem
+```
+
+---
+
+## Visual Options
+
+You can document storyboards with:
+
+### 1. Screenshots/Images
+
+Most precise. Capture exact states.
+
+```
+[Image: form-empty.png]
+[Image: form-filling.png]
+[Image: form-error.png]
+[Image: form-success.png]
+```
+
+### 2. ASCII Art
+
+Quick to create, easy to iterate.
+
+```
+Keyframe 0:        Keyframe 1:        Keyframe 2:
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│ Email        │   │ jane@...     │   │ jane@co.com  │
+└──────────────┘   └──────────────┘   └──────────────┘
+                                      ✓ Valid format
+```
+
+### 3. Description Only
+
+When visuals aren't critical.
+
+```
+Keyframe 0: Button shows "Submit"
+Keyframe 1: Button shows spinner, text hidden
+Keyframe 2: Button shows checkmark, turns green
+```
+
+### 4. Figma/Design Tool States
+
+Create component variants showing each state.
+
+---
+
+## Transition Types
+
+Document how states change:
+
+```
+INSTANT                   TIMED ANIMATION            DELAYED
+K0 ──► K1                K0 ─────────► K1           K0 ─ ─ ─► K1
+     0ms                      200ms                      300ms wait
+┌────┐ ┌────┐           ┌────┐   fade  ┌────┐      ┌────┐ wait ┌────┐
+│ A  │ │ A  │           │    │  ─────► │ ▓▓ │      │ X  │      │ X  │
+└────┘ └────┘           │    │   in    │ ▓▓ │      └────┘      │ ⚠  │
+Default Hover           └────┘         └────┘      No error    └────┘
+                        Hidden         Modal                    Error
+                                      visible                   appears
+
+No animation            Smooth fade    Prevents flash
+Instant feedback        200ms ease     After delay
+```
+
+### Instant
+
+```
+**Transition:** Instant (no animation)
+```
+
+Used for: Hover states, active states, error appearances
+
+### Timed Animation
+
+```
+**Transition:** 200ms ease-out
+```
+
+Used for: Modals, expandable sections, smooth state changes
+
+### Delayed
+
+```
+**Transition:** Appears after 300ms delay
+```
+
+Used for: Loading spinners (avoid flash), auto-dismiss messages
+
+### User-Triggered
+
+```
+**Transition:** On button click
+**Transition:** On input focus
+**Transition:** On scroll to element
+```
+
+### System-Triggered
+
+```
+**Transition:** On server response
+**Transition:** On data load complete
+**Transition:** On timer expiry
+```
+
+---
+
+## Grouping Storyboards
+
+Organize by element type:
+
+```
+Page Structure:
+┌─────────────────────────────────────────────────┐
+│ # Page: Signup Form                             │
+├─────────────────────────────────────────────────┤
+│ ## Form Fields                                  │
+│   ├── Email Field Storyboard ────┐              │
+│   │   K0 → K1 → K2                │ User input  │
+│   └── Password Field Storyboard ─┘              │
+│                                                  │
+│ ## Buttons                                      │
+│   ├── Submit Button Storyboard ──┐              │
+│   │   K0 → K1 → K2 → K3           │ Actions     │
+│   └── Back Button Storyboard ────┘              │
+│                                                  │
+│ ## System States                                │
+│   ├── Form Validation Storyboard ┐              │
+│   │   K0 → K1 → K2                │ Feedback    │
+│   └── Network Error Storyboard ──┘              │
+└─────────────────────────────────────────────────┘
+```
+
+**Documented Format:**
+
+```markdown
+# Page: Signup Form
+
+## Form Fields
+
+### Email Field Storyboard
+[keyframes...]
+
+### Password Field Storyboard
+[keyframes...]
+
+## Buttons
+
+### Submit Button Storyboard
+[keyframes...]
+
+### Back Button Storyboard
+[keyframes...]
+
+## System States
+
+### Form Validation Storyboard
+[keyframes...]
+
+### Network Error Storyboard
+[keyframes...]
+```
+
+---
+
+## The Freya Method
+
+Freya helps you think through transformations:
+
+> "When the user submits, what do they see while waiting?"
+
+> "This dropdown opens instantly. Should it animate for smoother UX?"
+
+> "The error appears, but how does the user know which field caused it?"
+
+She ensures every state change serves the user.
+
+---
+
+## What NOT to Storyboard
+
+**Skip storyboarding standard UI behaviors:**
+
+- **Button hover/active states** — Developers know these
+- **Link colors** — Standard browser behavior
+- **Focus states** — Design system handles this
+- **Cursor changes** — Standard pointer/text cursors
+- **Simple show/hide** — Basic visibility toggles
+- **Static content** — No interactivity
+
+**DO storyboard complex, non-standard transformations:**
+
+- **Async operations** — Loading → Success/Error flows
+- **Modal dialogs** — Open/close with animations
+- **Expandable sections** — Accordion behavior, content reveals
+- **Complex dropdowns** — Multi-level, searchable, filtered
+- **Form wizards** — Multi-step progress and validation
+- **Animations** — Custom entrance/exit effects
+- **Real-time updates** — Live data, notifications
+
+**The rule:** If it's a standard behavior developers already know, don't document it. If it's complex or custom, storyboard it.
+
+---
+
+## Connecting to Specifications
+
+Storyboards become part of your page specifications (Module 11):
+
+```markdown
+## Signup Form Specification
+
+### Submit Button
+- Component: Button (primary, large)
+- Label: "Create Account"
+- **Storyboard:** See Submit Button Storyboard
+
+### Email Field
+- Component: Input (email)
+- Label: "Email"
+- **Storyboard:** See Email Field Storyboard
+```
+
+The storyboard provides the dynamic behavior; the specification provides the full context.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Confusing with scenarios | Storyboards stay on one page |
+| Missing intermediate states | Show every step, not just start/end |
+| No "why" | Explain the purpose of each state |
+| Forgetting error states | What happens when things fail? |
+| Over-documenting | Focus on meaningful transformations |
+| No timing | Specify duration when it matters |
+
+---
+
+## Checklist
+
+For each interactive element:
+
+- [ ] Default state documented
+- [ ] All user-triggered states
+- [ ] All system-triggered states
+- [ ] Error states
+- [ ] Success states
+- [ ] Transition types specified
+- [ ] Timing where relevant
+- [ ] Why for each state
+
+---
+
+## What's Next
+
+In the tutorial, you'll create storyboards for the interactive elements in your own page sketches. Freya will guide you through identifying what needs storyboarding and documenting each transformation.
+
+---
+
+**[Continue to Tutorial: Create Your Storyboards →](tutorial-10.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-transformations.md) | [Back to Module Overview](module-10-storyboarding-overview.md)
+
+*Part of Module 10: Storyboarding*

package/docs/learn/module-10-storyboarding/module-10-storyboarding-overview.md

@@ -0,0 +1,290 @@
+# Module 10: Storyboarding
+
+**Time: 45 min | Agent: Freya | Phase: Design | Focus: UX**
+
+---
+
+## Transformations Within a View
+
+You have sketches of your pages. But pages aren't static.
+
+Things change. Elements transform. States shift.
+
+**Without leaving the page.**
+
+---
+
+## Scenario vs. Storyboard
+
+| Concept | What Changes | Example |
+|---------|--------------|---------|
+| **Scenario** | Logical views change | User navigates from Signup to Welcome |
+| **Storyboard** | Elements within a view change | Signup form shows loading → success → confetti |
+
+A scenario is the journey **across** pages.
+
+A storyboard is the transformation **within** a page.
+
+Think of it like a film: scenarios are scene changes, storyboards are what happens in each scene.
+
+---
+
+## The Comic Strip Analogy
+
+Think of storyboarding like a comic strip for your interface.
+
+```
+┌────────────────────────┐
+│  [Logo]      [Nav]     │     ┌──────────────────────────────────────────────┐
+├────────────────────────┤     │ SIGNUP FORM - STATE TRANSFORMATIONS          │
+│                        │     ├──────────────────────────────────────────────┤
+│   Hero Section         │     │                                              │
+│                        │     │  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐     │
+├────────────────────────┤     │  │  1   │  │  2   │  │  3   │  │  4   │     │
+│ ┌──────────────────┐   │ ──► │  │      │  │      │  │      │  │      │     │
+│ │                  │   │     │  │[btn] │  │ ...  │  │  ✓   │  │  🎉  │     │
+│ │   Signup Form    │◄──┼─┐   │  │      │  │      │  │      │  │      │     │
+│ │  (Focus area)    │   │ │   │  └──────┘  └──────┘  └──────┘  └──────┘     │
+│ └──────────────────┘   │ │   │   Click      Loading   Success   Celebrate  │
+│                        │ │   │   Button     State     Message   Animation   │
+├────────────────────────┤ │   │                                              │
+│   Footer               │ │   └──────────────────────────────────────────────┘
+└────────────────────────┘ │
+    Full Page              │
+    (Default State)        └─── Same section, 4 keyframes showing transformation
+```
+
+**The page stays the same. One section transforms.**
+
+Like a comic strip, each frame shows what changes:
+1. **Default** — User sees the button
+2. **Loading** — Button becomes spinner
+3. **Success** — Checkmark appears
+4. **Celebration** — Confetti animation
+
+---
+
+## The Default State
+
+Every page starts somewhere.
+
+This is **keyframe 0** — the default state of all objects on the screen.
+
+Your sketch from Module 09? That's typically the default state.
+
+What happens next is the storyboard.
+
+---
+
+## What Storyboards Capture
+
+Storyboards document **complex, non-standard transformations**:
+
+### Async Operations
+- Form submission → Loading → Success/Error
+- Data fetching → Skeleton screens → Content
+- File upload → Progress → Complete
+
+### User Interactions (Complex)
+- Accordion expand/collapse with animation
+- Modal dialogs opening and closing
+- Multi-step wizards with validation
+- Searchable/filterable dropdowns
+
+### Animations (Custom)
+- Entrance effects when content loads
+- Success celebrations (confetti, checkmarks)
+- Error shake animations
+- Progressive disclosure reveals
+
+### System State Changes
+- Real-time notifications appearing
+- Live data updates
+- Session timeout warnings
+- Conditional content showing/hiding
+
+**What storyboards DON'T capture:** Standard hover states, focus rings, simple link colors, or any behavior developers already know from design systems.
+
+---
+
+## Storyboard Format
+
+Add the storyboard images to the section in question.
+
+Specify step by step:
+
+**Visual Example:**
+
+```
+K0: Default          K1: User Types      K2: Strong          K3: Show Password
+┌────────────────┐  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
+│ Password       │  │ Password       │  │ Password       │  │ Password       │
+│ ┌────────────┐ │  │ ┌────────────┐ │  │ ┌────────────┐ │  │ ┌────────────┐ │
+│ │            │👁│  │ │ •••••      │👁│  │ │ ••••••••   │👁│  │ │MyP@ssw0rd! │👁│
+│ └────────────┘ │  │ └────────────┘ │  │ └────────────┘ │  │ └────────────┘ │
+│                │  │ [▌  ] Weak     │  │ [████▌] Strong │  │ [████▌] Strong │
+│                │  │                │  │      ✓         │  │      ✓         │
+└────────────────┘  └────────────────┘  └────────────────┘  └────────────────┘
+```
+
+**Documented Format:**
+
+```markdown
+## Password Field Storyboard
+
+### Keyframe 0: Default State
+[Image: password-field-default.png]
+- Input empty
+- Eye icon visible (closed)
+- No validation message
+
+### Keyframe 1: User Types
+[Image: password-field-typing.png]
+- Characters masked as dots
+- Strength indicator appears
+- Shows "Weak" in red
+
+### Keyframe 2: Password Strong
+[Image: password-field-strong.png]
+- Strength indicator fills
+- Shows "Strong" in green
+- Checkmark appears
+
+### Keyframe 3: Show Password
+[Image: password-field-visible.png]
+- User clicks eye icon
+- Characters become visible
+- Eye icon opens
+```
+
+---
+
+## Why Each Change Happens
+
+Don't just show what changes. Explain **why**.
+
+```
+The Complete Picture:
+
+K0              K1              K2              K3
+Empty    ─────► Typing   ─────► Strong   ─────► Visible
+                  │               │               │
+                  ▼               ▼               ▼
+               WHY: User       WHY: User       WHY: User
+               needs           needs           wants to
+               feedback        visual          verify
+               while           reinforcement   what they
+               typing                          typed
+```
+
+| Keyframe | What Changes | Why |
+|----------|--------------|-----|
+| 0 → 1 | Strength indicator appears | User needs feedback while typing |
+| 1 → 2 | Color shifts red → green | Reinforce password quality visually |
+| 2 → 3 | Characters visible | User wants to verify what they typed |
+
+---
+
+## The Freya Method
+
+Freya helps you think through on-page transformations:
+
+> "When the user submits, what do they see while waiting?"
+> "This dropdown opens instantly. Should it animate?"
+> "The error appears, but how does the user know which field?"
+
+She ensures every state change serves the user.
+
+---
+
+## What Needs Storyboarding
+
+Storyboard **complex, non-standard transformations**:
+
+```
+✅ DO STORYBOARD:                    ❌ DON'T STORYBOARD:
+
+Async Actions                        Button Hover
+┌──────┐ ┌──────┐ ┌──────┐          ┌──────┐ ┌──────┐
+│Submit│ │ ...  │ │  ✓   │          │Button│ │Button│
+└──────┘ └──────┘ └──────┘          └──────┘ └──────┘
+K0 → K1 → K2 → K3                    Default   Hover
+Complex flow                         Standard behavior
+
+Modal Dialog                         Focus Ring
+    ┌──────────────┐                 ┌──────────┐
+    │              │                 │ [Input ] │
+    │   Content    │                 └──────────┘
+    │              │                 Standard pattern
+    └──────────────┘
+Fade in, 200ms ease
+Custom animation
+```
+
+| Element | What to Storyboard |
+|---------|-------------------|
+| **Async Actions** | Submit → Loading → Success/Error states |
+| **Forms** | Multi-step validation, progressive disclosure, dynamic fields |
+| **Modals** | Open animation, content transitions, close behavior |
+| **Expandable Sections** | Collapsed → Expanded with content reveal |
+| **Complex Dropdowns** | Multi-level menus, filtered searches, dynamic options |
+| **Animations** | Entrance effects, celebration moments, transitions |
+| **Real-time Updates** | Live data appearing, notifications arriving |
+
+**Don't storyboard standard behaviors** like button hovers, link colors, or focus states — developers already know these.
+
+---
+
+## Output
+
+For each interactive section of your page:
+
+- Keyframe images showing transformation
+- Step-by-step description of changes
+- Reason for each change
+- Timing/duration where relevant
+
+This becomes the specification for developers.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Confusing with scenarios | Storyboards stay on one page |
+| Missing intermediate states | Show every step, not just start/end |
+| No "why" | Explain the purpose of each change |
+| Forgetting error states | What happens when things fail? |
+
+---
+
+## Practice
+
+Take one interactive section from your sketch:
+
+1. Identify the default state (keyframe 0)
+2. List all possible changes
+3. Draw/describe each keyframe
+4. Explain why each change happens
+5. Note timing if relevant
+
+---
+
+## Learn More
+
+- **[Lesson 1: Transformations](lesson-01-transformations.md)** — Understanding state changes within views
+- **[Lesson 2: Storyboard Format](lesson-02-storyboard-format.md)** — How to document keyframes effectively
+- **[Tutorial: Storyboard Your Views](tutorial-10.md)** — Hands-on practice with Freya
+
+---
+
+## Next Module
+
+**[Module 11: Conceptual Specifications →](../module-11-conceptual-specifications/module-11-conceptual-specifications-overview.md)**
+
+Document every decision.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*