storybook/design/ui-architecture.md

Storybook Editor UI Architecture

Structured creative tools for non-technical storytelling

Design Philosophy

Primary User (Lonni): Creative writer who thinks in characters, relationships, and narrative arcs—NOT files and syntax.

Secondary User (Sienna): Developer who needs access to raw .sb files for behavior trees, schemas, and engine integration.

Core Principle: The editor should feel like writing, not coding. Structured panes guide creation. The file editor is "manual mode" for power users.

Application Structure

┌─────────────────────────────────────────────────────────────────────┐
│  Storybook Editor - examples/alice-in-wonderland/                   │
├──────────────┬──────────────────────────────────────┬───────────────┤
│              │                                      │               │
│   Entity     │        Character Editor              │  Quick        │
│   Browser    │                                      │  Actions      │
│              │  ┌─────────────────────────────────┐ │               │
│  Characters  │  │ Name: Alice                     │ │ ✓ Validate    │
│  ├─ Alice    │  │ Age: 7                          │ │ ⎇ Versions    │
│  ├─ Rabbit   │  │ Species: Human                  │ │ ⊕ New Char    │
│  └─ Queen    │  │                                 │ │ ⊕ New Rel     │
│              │  │ Traits                          │ │ ⊕ New Place   │
│  Relations   │  │  curiosity: 0.95 [━━━━━━━━━•─] │ │               │
│  ├─ Alice    │  │  politeness: 0.75 [━━━━━━━•───] │ │ 🔍 Search...  │
│  │  ↔ Rabbit │  │                                 │ │               │
│  └─ Queen    │  │ Backstory                       │ │ Git           │
│     ↔ King   │  │ ┌─────────────────────────────┐ │ │  main         │
│              │  │ │ Alice was beginning to get  │ │ │  3m ago       │
│  Places      │  │ │ very tired of sitting by    │ │ │  12 changes   │
│  ├─ Rabbit   │  │ │ her sister on the bank...   │ │ │               │
│  │  Hole     │  │ │                             │ │ └───────────────┘
│  └─ Tea      │  │ └─────────────────────────────┘ │
│     Party    │  │                                 │
│              │  │ [Portrait slot: click to add]   │
│  Schedules   │  │                                 │
│  Templates   │  │             [Save Character]    │
│  Behaviors   │  └─────────────────────────────────┘
│              │                                      │
│  [Manual]    │  Tabs: Traits | Backstory | Schedule│
│              │        Relationships | Behavior     │
└──────────────┴──────────────────────────────────────┴───────────────┘

Primary Views (Structured Editing)

1. Character Editor

Purpose: Create and edit characters through forms and rich text, NOT raw .sb syntax.

Layout:

• Header: Name input (large, prominent)
• Metadata Row: Age, species, template dropdowns
• Traits Section: Sliders for numeric traits, chips for tags
• Prose Sections: Tabbed rich text areas for backstory, appearance, personality
• Portrait: Image upload with preview
• Relationships: Quick list with "Edit" buttons
• Schedule: Mini timeline preview with "Edit Full Schedule" button

Interaction:

• All changes auto-save to .sb file (no explicit save button for small edits)
• Git auto-commit on major milestones (e.g., "Update Alice: added backstory")
• Validation errors show inline (e.g., red border + tooltip for out-of-range trait)

Example:

┌─────────────────────────────────────────────────────┐
│ Name: Alice                               [Portrait]│
│ Age: 7    Species: Human    Template: Child         │
├─────────────────────────────────────────────────────┤
│ Traits                                              │
│  curiosity     0.95  [━━━━━━━━━━━━━━━•─]           │
│  politeness    0.75  [━━━━━━━━━━━•─────]           │
│  fear_of_queen 0.10  [━•──────────────────]         │
│                                                     │
│  Tags: [imaginative] [brave] [+ Add Tag]           │
├─────────────────────────────────────────────────────┤
│ ⎔ Backstory  │  Appearance  │  Personality         │
├─────────────────────────────────────────────────────┤
│ Alice was beginning to get very tired of sitting    │
│ by her sister on the bank, and of having nothing    │
│ to do...                                            │
│                                                     │
│ [Rich text editor with basic formatting]           │
└─────────────────────────────────────────────────────┘

2. Relationship Editor

Purpose: Visually connect characters and define relationship properties.

Layout:

• Graph View: Force-directed graph with character nodes
• Edge Selection: Click edge to edit relationship details
• Properties Panel: Bond strength, coordination level, bond type
• Asymmetric Fields: "From Alice's perspective" / "From Rabbit's perspective"

Interaction:

• Drag nodes to rearrange
• Click edge → properties panel appears
• Slider for bond strength (0.0 to 1.0)
• Dropdown for bond type (romantic, familial, friendship, etc.)

Example:

┌─────────────────────────────────────────────────────────────┐
│ Relationship: Alice ↔ White Rabbit                          │
├─────────────────────────────────────────────────────────────┤
│  Bond Strength: 0.65  [━━━━━━━•──────]                      │
│  Bond Type: friendship                                      │
│  Coordination: ad_hoc                                       │
├─────────────────────────────────────────────────────────────┤
│  From Alice's perspective:                                  │
│    Respect for punctuality: 0.80 [━━━━━━━━•──]             │
│                                                             │
│  From White Rabbit's perspective:                           │
│    Anxiety about lateness: 0.95 [━━━━━━━━━━━•─]            │
├─────────────────────────────────────────────────────────────┤
│                   [Graph View]                              │
│                                                             │
│        Alice ●━━━━━━● White Rabbit                         │
│                                                             │
│    Queen ●━━━━━━━━━━● King                                 │
│       ╲             ╱                                       │
│        ●━━━━━━━━━━●                                         │
│       Guards                                                │
└─────────────────────────────────────────────────────────────┘

3. Schedule Builder

Purpose: Visual timeline for daily routines (no typing time codes!).

Layout:

• Timeline: Horizontal 24-hour view with draggable blocks
• Activity Palette: Drag activities from sidebar onto timeline
• Activity Editor: Click block to edit parameters

Interaction:

• Drag edges to resize time blocks
• Drag from palette to add new activity
• Snap to 15-minute increments
• Validation: overlapping blocks show warning

Example:

┌─────────────────────────────────────────────────────────────┐
│ Schedule: Alice's Day                                        │
├────┬────────────────────────────────────────────────────────┤
│    │ 00:00     06:00     12:00     18:00     24:00         │
│    ├───────────────────────────────────────────────────────┤
│ Su │ ████Sleep████│Breakfast│Play│Tea│Study│Play│█Sleep██  │
│ Mo │ ████Sleep████│Breakfast│School██████│Play│██Sleep███  │
│    └───────────────────────────────────────────────────────┘
│                                                             │
│ Palette:                                                    │
│  [Sleep] [Eat] [Play] [Study] [Social] [+ Custom]          │
│                                                             │
│ Selected: Tea Party (16:00 → 17:00)                        │
│  Location: Garden                                           │
│  Participants: Mad Hatter, March Hare, Dormouse            │
└─────────────────────────────────────────────────────────────┘

4. Behavior Tree Builder (Advanced)

Purpose: Visual node graph for programmable behaviors (Sienna's domain, but approachable for Lonni).

Layout:

• Canvas: Infinite 2D space for nodes
• Node Palette: Selector, Sequence, Condition, Action, Decorator
• Inspector: Selected node's properties

Interaction:

• Drag nodes from palette
• Connect with edges (parent → children)
• Right-click node → context menu (delete, duplicate, etc.)
• Validation: orphan nodes, missing actions show errors

Example:

┌─────────────────────────────────────────────────────────────┐
│ Behavior: WorkAtBakery                                      │
├─────────────────────────────────────────────────────────────┤
│  Palette: [Selector] [Sequence] [?Condition] [→Action]     │
│                                                             │
│  Canvas:                                                    │
│                                                             │
│           ┌─────────────┐                                   │
│           │  Selector   │                                   │
│           └──────┬──────┘                                   │
│         ┌────────┼────────┐                                 │
│         ▼        ▼        ▼                                 │
│     ┌──────┐ ┌──────┐ ┌──────┐                             │
│     │ Prep │ │ Bake │ │ Sell │                             │
│     │ Dough│ │Bread │ │ Bread│                             │
│     └──────┘ └──────┘ └──────┘                             │
│                                                             │
│  Selected: PrepDough                                        │
│    Action: knead_dough                                      │
│    Duration: 30 minutes                                     │
│    Required Skill: baking > 0.5                             │
└─────────────────────────────────────────────────────────────┘

Secondary View (Manual Mode)

File Editor

Purpose: Direct .sb syntax editing for power users and edge cases.

When to Use:

• Behavior trees (until visual editor is built)
• Templates with ranges
• Advanced features not yet in GUI
• Bulk find-replace across characters

Layout:

• Syntax-highlighted text editor (Monaspace Neon)
• Live validation with inline errors
• File tree on left

Interaction:

• Standard text editor keybindings
• Ctrl+S saves (git auto-commit)
• Errors show inline with gold underline
• Click error → jump to diagnostic

Entity Browser (Left Sidebar)

Purpose: Navigate the storybook's content hierarchy.

Structure:

📂 characters/
├─ 👤 Alice
├─ 🐰 White Rabbit
├─ 👑 Queen of Hearts
└─ 👑 King of Hearts

💑 relationships/
├─ Alice ↔ White Rabbit
├─ Queen ↔ King
└─ Queen → Subjects (all)

📍 locations/
├─ 🕳️ Rabbit Hole
├─ 🫖 Tea Party Garden
└─ 🏰 Queen's Castle

📋 templates/
├─ WonderlandCreature
├─ PlayingCard
└─ CourtMember

🎭 behaviors/
├─ WorkAtBakery
└─ AttendTeaParty

📅 schedules/
└─ DailyRoutine

Interaction:

• Click entity → load in main panel
• Right-click → context menu (delete, duplicate, etc.)
• Drag-drop to reorder or move files
• Search box filters by name

Quick Actions Pane (Right Sidebar)

Purpose: Common tasks and project status at fingertips.

Sections:

1. Actions

   • ✓ Validate All
   • ⊕ New Character
   • ⊕ New Relationship
   • ⊕ New Location
   • 🔍 Search Everything

2. Git Status

   • Current branch: main
   • Last change: 3 minutes ago
   • Uncommitted changes: 12 files
   • [View History] button → timeline view

3. Diagnostics

   • ✓ No errors
   • ⚠ 2 warnings
   • Click to expand inline

4. Project Info

   • Characters: 12
   • Relationships: 7
   • Locations: 5

Responsive Behavior

Wide Screen (> 1440px)

Three columns: Entity Browser | Main Editor | Quick Actions

Standard (1024–1440px)

Two columns: Entity Browser | Main Editor Quick Actions → collapsible panel

Compact (< 1024px)

Single column focus mode Entity Browser → drawer (slides in from left) Quick Actions → toolbar at top

Technical Implementation Notes

Iced Framework

• Use iced::widget::* for built-in components
• Custom widgets for:
  • Timeline (schedule builder)
  • Graph (relationship map)
  • Node Canvas (behavior tree builder)
  • Trait Slider (with live value display)

File Synchronization

• Watch .sb files for external changes
• Reload editor state on change
• Warn if unsaved changes conflict

Git Integration

• Auto-commit on save with descriptive messages:
  • "Update Alice: modified backstory"
  • "Add relationship: Alice ↔ White Rabbit"
  • "Create character: Cheshire Cat"
• Use git2 crate (no shell commands)
• Expose branches as "versions" in UI

Theme Application

• Load colors from design/color-palette.md
• Apply 8px grid to all spacing
• Use Monaspace Neon for code blocks
• Geist for UI text
• Gradient background: aubergine (sides) → cream (center) in main editor panel

User Workflows

Lonni Creates a New Character

1. Click "⊕ New Character" in Quick Actions
2. Fill in name, age, species (dropdowns guided by schema)
3. Adjust trait sliders (validation prevents out-of-range)
4. Write backstory in rich text area
5. Upload portrait image
6. Click "Save" → .sb file created, git commit happens
7. Character appears in Entity Browser

Lonni Builds a Relationship

1. Click "⊕ New Relationship"
2. Select two characters from dropdowns
3. Drag bond strength slider
4. Pick bond type from predefined options
5. Fill in asymmetric fields (Alice's view vs. Rabbit's view)
6. Save → .sb file updated, git commit

Sienna Edits a Behavior Tree

1. Click behavior in Entity Browser
2. See visual node graph
3. Drag new "Action" node from palette
4. Connect to parent Sequence
5. Set action parameters in inspector
6. Save → .sb file updated

Both Users Check Validation

1. Quick Actions shows "⚠ 2 warnings"
2. Click to expand → shows inline errors
3. Click error → jumps to problematic entity
4. Fix in structured editor
5. Validation updates live

---

This architecture prioritizes Lonni's creative flow while keeping power-user features accessible for Sienna.