17 KiB
17 KiB
Storyboard Integration Guide
Using Visual Storyboards to Document Complex Component Functionality
Problem Statement
Complex interactive components (calendars, booking systems, multi-step workflows) have state transitions and interaction flows that are difficult to describe in text alone.
Storyboards provide visual, sequential documentation of:
- State transitions (e.g., Empty → Booked → Active → Completed)
- User interactions and system responses
- Time-based changes (countdowns, timers)
- Multi-step workflows
Storyboard Types
1. State Transition Storyboards
Purpose: Show how a component changes states over time
Example: Dog Week Walk Booking States
┌─────────────────────────────────────────────────┐
│ State Transition Storyboard │
│ Component: Walk Time Slot Card │
├─────────────────────────────────────────────────┤
│ │
│ 1. WHITE (Empty) → User books │
│ [Dog icon] 8-11 → [Book button] │
│ │
│ 2. GRAY (Booked) → Time arrives │
│ [Dog+User] 8-11 │
│ │
│ 3. ORANGE (Countdown) → User starts │
│ [Dog icon] 32 min left → [Start button] │
│ │
│ 4. BLUE (In Progress) → User completes │
│ [Dog+User] Started 09:32 • 23 min ago │
│ │
│ 5. GREEN (Completed) → Final state │
│ [Dog+User] 32 min walk ✓ │
│ │
│ Alt: RED (Missed) → Window expired │
│ [Dog icon] No walk registered ⊖ │
│ │
└─────────────────────────────────────────────────┘
File: Sketches/App-Main-Booking-States.jpg (Dog Week example)
2. Interaction Flow Storyboards
Purpose: Show step-by-step user interactions
Example: Calendar Booking Flow
Frame 1: User views calendar
Frame 2: User taps "Book" button
Frame 3: Card transitions to GRAY state
Frame 4: Leaderboard updates (+1 point)
Frame 5: Week overview quarter circle turns gray
3. Multi-Component Storyboards
Purpose: Show how multiple components interact
Example: Week View + Leaderboard + Calendar Sync
Frame 1: User clicks day circle in week overview
Frame 2: Calendar scrolls to that day
Frame 3: User books walk
Frame 4: Week overview quarter circle updates
Frame 5: Leaderboard count increments
Integration with Modular Structure
Where Storyboards Belong
| File Type | Contains Storyboard? | Purpose |
|---|---|---|
| Pages/ | ❌ No | Page layout only |
| Components/ | ⚠️ Visual states only | Static appearance of each state |
| Features/ | ✅ YES | State transitions & interaction flows |
Storyboard Storage
project-root/
├─ Pages/
│ └─ 02-calendar-page.md
│
├─ Components/
│ └─ walk-slot-card.component.md
│
├─ Features/
│ ├─ walk-booking-logic.feature.md
│ └─ Storyboards/ ← NEW FOLDER
│ ├─ walk-state-transitions.jpg
│ ├─ booking-flow.jpg
│ └─ calendar-sync-flow.jpg
│
└─ Sketches/ ← Existing page sketches
└─ 02-calendar-page-sketch.jpg
Feature File with Storyboard Reference
Example: walk-booking-logic.feature.md
# Walk Booking Logic Feature
**Feature ID:** `walk-booking-logic`
**Type:** State Machine with Time-Based Transitions
**Complexity:** High
## Purpose
Manages walk slot state transitions, user booking interactions, and automatic time-based state changes for the Dog Week calendar.
---
## Visual Storyboard
**State Transition Flow:**
**Key:** This storyboard shows all 6 walk states and the triggers that cause transitions between them.
---
## State Definitions
### State 1: WHITE (Empty / Available)
**Visual Reference:** Storyboard Frame 1
**Appearance:**
- White background
- Dog avatar only (no user avatar)
- Time range: "8-11"
- Action button: "Book" / "Boka"
**Triggers:**
- Initial state for all unbooked slots
- Appears when walk is unbooked
**Transitions:**
- User clicks "Book" → GRAY (Booked)
**Business Rules:**
- Any family member can book
- Booking awards +1 leaderboard point
- Updates week overview quarter circle to gray
---
### State 2: GRAY (Booked / Scheduled)
**Visual Reference:** Storyboard Frame 2
**Appearance:**
- Gray background
- Dog avatar + User avatar overlay
- Names: "Rufus & Patrick"
- Time range: "8-11"
- No action button (tap card for details)
**Triggers:**
- User books empty slot (WHITE → GRAY)
- Walk is scheduled but time window not yet open
**Transitions:**
- Time window opens (8:00 arrives) → ORANGE (Countdown)
- User unbooks walk → WHITE (Empty)
**Business Rules:**
- Shows who booked the walk
- Tap card to view details/unbook
- Leaderboard point already awarded
---
### State 3: ORANGE (Window Open / Countdown)
**Visual Reference:** Storyboard Frame 3
**Appearance:**
- Orange background
- Dog avatar only (user avatar removed)
- Countdown timer: "32 min left" / "32 min kvar"
- Warning icon: ⚠️
- Action button: "Start" / "Starta"
**Triggers:**
- Scheduled time arrives (8:00) → GRAY to ORANGE
- Real-time countdown updates every minute
**Transitions:**
- User clicks "Start" → BLUE (In Progress)
- Countdown reaches 0 (11:00) → RED (Missed)
**Business Rules:**
- Countdown shows time remaining in window
- Urgency indicator (warning icon)
- Can only start if no other walk active for this dog
---
### State 4: BLUE (In Progress / Active Walk)
**Visual Reference:** Storyboard Frame 4
**Appearance:**
- Blue background
- Dog avatar + User avatar overlay
- Status: "Started 09:32 • 23 min ago"
- Refresh icon: ↻
- No action button (tap card for completion)
**Triggers:**
- User starts walk (ORANGE → BLUE)
- Real-time duration updates every minute
**Transitions:**
- User completes walk → GREEN (Completed)
**Business Rules:**
- Blocks other walks for this dog
- Shows elapsed time since start
- Tap card to complete walk or view progress
---
### State 5: GREEN (Completed)
**Visual Reference:** Storyboard Frame 5
**Appearance:**
- Green background
- Dog avatar + User avatar overlay
- Duration: "32 min walk" / "32 min promenad"
- Checkmark icon: ✓
- No action button
**Triggers:**
- User completes active walk (BLUE → GREEN)
**Transitions:**
- None (final successful state)
**Business Rules:**
- Permanent record of completed walk
- Shows actual walk duration
- Unblocks dog for next walk
---
### State 6: RED (Missed / Overdue)
**Visual Reference:** Storyboard Frame 6
**Appearance:**
- Red background
- Dog avatar only (no user avatar)
- Message: "No walk registered" / "Ingen promenad registrerad"
- Minus icon: ⊖
- No action button
**Triggers:**
- Countdown expires without walk being started (ORANGE → RED)
**Transitions:**
- None (permanent accountability record)
**Business Rules:**
- Cannot be changed or deleted
- Leaderboard point remains (no penalty)
- Shows who booked but didn't complete
---
## Interaction Flows
### Flow 1: Successful Walk Booking & Completion
**Storyboard:** `Storyboards/booking-flow.jpg`
**Steps:**
1. **User views empty slot** (WHITE state)
- Sees "Book" button
2. **User taps "Book"**
- System validates user is family member
- System creates booking record
3. **Immediate updates:**
- Card → GRAY state
- Leaderboard: User +1 point
- Week overview: Quarter circle → gray
4. **Time window opens** (8:00 arrives)
- Card → ORANGE state
- Countdown timer starts
5. **User taps "Start"**
- System validates no other active walk for dog
- System records start time
6. **Immediate updates:**
- Card → BLUE state
- Duration counter starts
- Other walks for dog → disabled
7. **User completes walk** (via Walk Details page)
- System records completion time
- System calculates duration
8. **Immediate updates:**
- Card → GREEN state
- Week overview: Quarter circle → green
- Other walks for dog → re-enabled
---
### Flow 2: Missed Walk
**Storyboard:** `Storyboards/missed-walk-flow.jpg`
**Steps:**
1. Walk booked (GRAY state)
2. Time window opens (ORANGE state)
3. Countdown timer runs
4. User doesn't start walk
5. Countdown reaches 0 (11:00)
6. **Automatic transition:** ORANGE → RED
7. Permanent missed walk record created
---
### Flow 3: Multi-Component Sync
**Storyboard:** `Storyboards/calendar-sync-flow.jpg`
**Components Involved:**
- Week Overview (top section)
- Leaderboard (middle section)
- Booking Calendar (bottom section)
**Sync Flow:**
1. User books walk in calendar
2. **Sync 1:** Week overview quarter circle updates
3. **Sync 2:** Leaderboard count increments
4. User starts walk
5. **Sync 3:** Week overview quarter circle changes color
6. User completes walk
7. **Sync 4:** Week overview quarter circle turns green
---
## State Machine Diagram
┌─────────────┐
│ WHITE │
│ (Empty) │
└──────┬──────┘
│ User books
▼
┌─────────────┐
│ GRAY │
│ (Booked) │
└──────┬──────┘
│ Time arrives
▼
┌─────────────┐
│ ORANGE │◄──── Countdown timer
│ (Countdown) │ updates every 1 min
└──┬───────┬──┘
│ │
User starts │ │ Countdown expires
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ BLUE │ │ RED │
│(Active) │ │(Missed) │
└────┬────┘ └─────────┘
│ │
User completes │ │ Permanent
│ │ record
▼ ▼
┌─────────┐ [END]
│ GREEN │
│(Complete)│
└─────────┘
│
▼
[END]
---
## Storyboard Creation Guidelines
### When to Create Storyboards
Create storyboards for:
- ✅ Components with 3+ states
- ✅ Time-based transitions (countdowns, timers)
- ✅ Multi-step user flows
- ✅ Complex interactions between multiple components
- ✅ State machines with branching paths
Don't need storyboards for:
- ❌ Simple buttons (hover, active states)
- ❌ Static content sections
- ❌ Single-state components
### Storyboard Format
**Hand-drawn sketches** (recommended):
- Quick to create
- Easy to iterate
- Focus on functionality, not polish
- Example: Dog Week `App-Main-Booking-States.jpg`
**Digital wireframes:**
- Use Figma, Sketch, or similar
- More polished for client presentations
- Easier to update
**Annotated screenshots:**
- Use actual prototype screenshots
- Add arrows and labels
- Good for documenting existing systems
### Storyboard Numbering
Number frames sequentially:
- Initial state
- After user action
- System response
- Next state
- Alternative path
### Storyboard Annotations
Include:
- **State names** (e.g., "ORANGE - Countdown")
- **Trigger descriptions** (e.g., "User taps Start")
- **Time indicators** (e.g., "After 32 minutes")
- **Icons/symbols** for actions (→ for transitions, ⚠️ for warnings)
---
## Feature File Template with Storyboard
```markdown
# {Feature Name} Feature
**Feature ID:** `{feature-id}`
**Type:** {State Machine / Workflow / Calculator / etc.}
**Complexity:** {Low / Medium / High}
## Purpose
{Brief description of what this feature does}
---
## Visual Storyboard
**{Storyboard Type}:**
**Key:** {Brief explanation of what the storyboard shows}
---
## State Definitions
{If applicable - for state machines}
### State 1: {State Name}
**Visual Reference:** Storyboard Frame {number}
**Appearance:**
- {Visual description}
**Triggers:**
- {What causes this state}
**Transitions:**
- {What states this can transition to}
**Business Rules:**
- {Rules governing this state}
---
## Interaction Flows
### Flow 1: {Flow Name}
**Storyboard:** `Storyboards/{flow-storyboard}.jpg`
**Steps:**
1. {Step description}
2. {Step description}
3. {Step description}
---
## State Machine Diagram
{ASCII diagram showing state transitions}
---
## Data Requirements
{API endpoints, data models, etc.}
---
## Validation Rules
{Business rules, constraints, etc.}
---
## Error Handling
{Error states, recovery flows, etc.}
Dog Week Example: Complete Structure
Features/
├─ walk-booking-logic.feature.md
│ ├─ References: Storyboards/walk-state-transitions.jpg
│ ├─ Contains: 6 state definitions
│ └─ Contains: State machine diagram
│
├─ calendar-sync.feature.md
│ ├─ References: Storyboards/calendar-sync-flow.jpg
│ └─ Contains: Multi-component interaction flows
│
└─ Storyboards/
├─ walk-state-transitions.jpg ← Main state storyboard
├─ booking-flow.jpg ← Successful booking flow
├─ missed-walk-flow.jpg ← Missed walk scenario
├─ calendar-sync-flow.jpg ← Component sync flow
└─ week-navigation-flow.jpg ← Week navigation interactions
Benefits of Storyboard Integration
1. Visual Clarity
Before (Text only):
When the user books a walk, the card changes to gray,
the leaderboard updates, and the week overview changes.
After (With storyboard):
See Storyboard Frame 2-3 for visual state transition.
2. Developer Understanding
Developers can:
- See exact visual states
- Understand transition triggers
- Identify edge cases visually
- Reference storyboard during implementation
3. Design Consistency
Designers can:
- Ensure all states are visually distinct
- Verify state transitions make sense
- Spot missing states or transitions
- Create Figma components matching storyboard
4. QA Testing
QA can:
- Use storyboard as test script
- Verify all states are implemented
- Test all transition paths
- Identify missing functionality
Workflow Integration
Step 1: Sketch Storyboard
During UX design phase:
- Identify complex interactive components
- Sketch state transitions on paper/whiteboard
- Number frames sequentially
- Add annotations for triggers and transitions
- Take photo or scan
Step 2: Store Storyboard
Features/Storyboards/{component-name}-{type}.jpg
Step 3: Reference in Feature File
## Visual Storyboard
Step 4: Document States
For each frame in storyboard:
- Create state definition
- Link to storyboard frame number
- Describe triggers and transitions
Step 5: Create State Machine
Convert storyboard to ASCII state machine diagram for quick reference
Summary
Storyboards are essential for:
- 🎯 Complex state machines (calendars, booking systems)
- 🎯 Multi-step workflows (onboarding, checkout)
- 🎯 Time-based interactions (countdowns, timers)
- 🎯 Multi-component synchronization
Store storyboards in:
Features/Storyboards/folder- Reference from Feature files
- Link to specific frames in state definitions
Benefits:
- ✅ Visual clarity for developers
- ✅ Design consistency
- ✅ QA test scripts
- ✅ Stakeholder communication
- ✅ Documentation that doesn't get stale
Result: Complex component functionality is documented visually and textually, making implementation and testing straightforward.