storyteller/docs/reference/UI_ELEMENTS_REFERENCE.md

UI Elements Reference - Storyteller RPG

Purpose: Complete catalog of UI elements for design system templates
Date: October 12, 2025

---

🎨 Design System Overview

Color Palette

• Primary: Purple gradient (#667eea to #764ba2)
• Background: Dark theme (#1a1a2e, #16213e)
• Success: Green (#10b981, #86efac)
• Text: White (#fff), Light gray (#aaa, #ccc)
• Borders: Subtle white rgba (0.1 opacity)

Typography

• Headings: 24-32px, bold
• Body: 14-16px, normal
• Small: 12-13px, secondary info

---

📄 Page 1: Session Setup / Landing Page

Purpose

Entry point for creating/joining sessions and characters

Key Sections

1. Header Area

• App Title: "🎭 Storyteller RPG"
• Subtitle: Brief tagline
• Logo placeholder (future)

2. Demo Session Quick Access

• Section Title: "🎲 Demo Session - 'The Cursed Tavern'"
• Description text: Brief explanation
• Three action buttons:
  • Join as Storyteller (gold gradient)
  • Play as Bargin (character 1)
  • Play as Willow (character 2)
• Button styling: Large, prominent, with icons

3. Session Creation Section

• Section Title: "Create New Session"
• Description: "Start a new game as the storyteller"
• Input field: Session name (text)
• Primary button: "Create Session"

4. Session Join Section

• Section Title: "Join Existing Session"
• Description: "Play as a character in an ongoing game"
• Form elements:
  • Session ID input (text)
  • Character name input (text, required)
  • Description textarea (3 rows)
  • Personality textarea (2 rows, optional)
  • Model selector (dropdown with optgroups)
  • Model hint text (small, gray)
• Character creation options:
  • Primary button: "✨ Create Character (Wizard)"
  • Divider: "or"
  • Toggle button: "Quick Create" (shows simple form)
• Submit button: "Join Session (Simple)" (conditional)

5. Dividers

• Horizontal rule with centered text ("OR")
• Visual separation between sections

---

📄 Page 2: Character View (Player Perspective)

Purpose

Player's interface for interacting with storyteller

Layout Structure

Three-column layout: Info | Messages | Public Feed

Key Sections

1. Character Header

• Character name (h2, white, bold)
• Description text (gray, italic)
• Personality traits (with emoji prefix)
• Profile badges (if profile exists):
  • Race badge
  • Class badge
  • Personality type badge
• Action buttons:
  • Export button (📥)
  • Connection status indicator (● Connected / ○ Disconnected)

2. Current Scene Panel (if active)

• Section title: "📜 Current Scene"
• Scene text (large, prominent)
• Background: Highlighted panel

3. Public Messages Section

• Section title: "📢 Public Actions (All Players See)"
• Message list:
  • Message sender label
  • Timestamp
  • Message content
  • Visual distinction from private messages

4. Private Conversation Area

• Section title: "💬 Private Conversation with Storyteller"
• Message thread:
  • Character messages (right-aligned, colored)
  • Storyteller messages (left-aligned, different color)
  • Timestamps
  • Message bubbles
• Auto-scroll to latest

5. Message Composer

• Message visibility selector (dropdown):
  • Private
  • Public
  • Mixed
• Input area (varies by type):
  • Private/Public: Single text input
  • Mixed: Two textareas (public + private)
• Send button (primary, disabled when disconnected)

6. AI Generation Section (future)

• Generate suggestion button
• Prompt customization
• Regenerate option

---

📄 Page 3: Storyteller View (GM Perspective)

Purpose

Game master interface to manage all players and narrate story

Layout Structure

Two-column: Character list sidebar | Main content area

Key Sections

1. Session Header

• Session name (h2)
• Session ID display with copy button
• Quick copy feedback (tooltip/toast)

2. Character List Sidebar

• Section title: "Active Characters"
• Character cards:
  • Character name
  • "💬 View" button (per character)
  • Highlight active selection
  • Pending response indicator (red dot)
• Scrollable list

3. Scene Narration Panel

• Section title: "📜 Scene Narration"
• Textarea: Large input for scene description
• Buttons:
  • "Broadcast Scene" (primary)
  • "✨ AI Suggest" (secondary, generates scene)

4. Public Actions Feed

• Section title: "📢 Recent Public Actions"
• Message list:
  • Character name
  • Action content
  • Timestamp
• Latest 5 messages shown

5. Character Conversation View

• Header: Selected character name
• Conversation thread:
  • Character messages
  • Your responses
  • Timestamps
• Response composer:
  • Large textarea
  • Button group:
    • "✨ AI Suggest"
    • "Send Private Response"

6. Multi-Character Response (future)

• Select multiple characters
• Generate context-aware response
• Broadcast to selected players

---

📄 Page 4: Character Creation Wizard

Purpose

6-step guided character creation with profiles

Layout Structure

Modal overlay with centered card

Key Sections

1. Wizard Header

• Title: "Create Your Character"
• Progress indicator:
  • 6 steps shown
  • Active step highlighted
  • Step labels visible

2. Step Navigation

• Footer buttons:
  • Cancel (left)
  • Back (if not step 1)
  • Next (steps 1-5)
  • Create Character (step 6)

Step-by-Step UI Elements

Step 1: Basic Info

• Form elements:
  • Name input (required)
  • Gender selector (dropdown)
• Import section:
  • Hint text
  • Import from JSON button (file picker)

Step 2: Description

• Form elements:
  • Description textarea (4 rows, required)
  • Background textarea (3 rows, optional)

Step 3: Race & Class

• Selection grids: (2x3 or responsive)
  • Race cards (clickable)
  • Class cards (clickable)
• Card elements:
  • Name (bold)
  • Description (gray)
  • Selected state (highlighted border, gradient background)
  • Hover effects

Step 4: Personality

• Selection grid: 2x2
  • Personality type cards
  • Same card styling as Step 3
• Additional traits textarea (optional)

Step 5: AI Model

• Model selector: Large dropdown
  • Optgroups (OpenAI, OpenRouter)
  • Model names with providers
• Hint text: Model personality differences

Step 6: Review

• Preview panels:
  • Basic Information
  • Description
  • Background (if provided)
  • Additional Traits (if provided)
  • AI Model
• Summary card:
  • Character identity statement
  • Highlighted/special styling

---

📄 Future Pages (Phase 3+)

Gamemaster Dashboard

• Game creation wizard
• Player slot assignment
• Role management grid
• Game state overview
• AI control panel

Admin Panel

• System overview
• User management
• LLM configuration
• Cost tracking dashboard
• Analytics charts

Character Sheet (Enhanced)

• Stats display
• Inventory grid
• Skills list
• Equipment slots
• Character progression

---

🎨 Common UI Components

Buttons

1. Primary button: Purple gradient, white text
2. Secondary button: Transparent, border, hover effect
3. Wizard button: Extra gradient styling
4. Export/Action buttons: Subtle rgba background
5. Icon buttons: Small, inline

Form Elements

1. Text inputs: Dark background, subtle border, focus glow
2. Textareas: Resizable, same styling as inputs
3. Dropdowns: Custom styling, optgroups
4. File pickers: Hidden, triggered by styled button

Cards

1. Selection cards: Clickable, hover lift, selected state
2. Character cards: Compact, button included
3. Message cards: Bubbles, aligned left/right
4. Preview panels: Bordered sections with headers

Indicators

1. Status dots: Colored circles (● ○)
2. Badges: Rounded rectangles, colored background
3. Progress bars: Step indicators
4. Loading states: Spinners, skeleton screens

Feedback

1. Toasts/Alerts: Success/error messages
2. Tooltips: Hover information
3. Validation messages: Inline form errors
4. Empty states: No data placeholders

---

📐 Layout Patterns

Responsive Breakpoints

• Desktop: > 768px (multi-column)
• Mobile: ≤ 768px (single column, stacked)

Grid Systems

• 2-column: Sidebar + main content
• 3-column: Info + center + sidebar
• Selection grids: Auto-fit, min 200px

Spacing

• Sections: 2-3rem padding
• Elements: 1-1.5rem gaps
• Inline: 0.5-1rem margins

---

🎯 Design Prompt Template

For UI Design LLM:

Create a modern, dark-themed UI design for [PAGE NAME] with these elements:

**Color Scheme:**
- Primary: Purple gradient (#667eea to #764ba2)
- Background: Dark navy (#1a1a2e, #16213e)
- Accents: White with 10% opacity borders
- Text: White and light gray

**Layout:**
[Describe specific layout]

**Components Needed:**
[List specific elements for that page]

**Style:**
- Modern, clean, RPG-themed
- Smooth gradients and shadows
- Glassmorphism effects
- Smooth hover animations
- Mobile responsive

**Inspiration:**
Discord's UI, modern game interfaces, fantasy themes

---

📊 Component Priority

Essential (Implement First)

1. Session setup forms
2. Message display/composer
3. Character header/info
4. Navigation/buttons

Important (Phase 2-3)

1. Character creation wizard
2. Storyteller dashboard
3. Profile displays
4. Export/import UI

Nice-to-Have (Phase 4+)

1. Character sheets with stats
2. Inventory management
3. Dice roller UI
4. Image generation panels
5. Analytics dashboards

---

Total UI Elements Cataloged: 100+
Pages Documented: 4 (+ 3 future)
Ready for design system creation ✅