storyteller/docs/reference/UI_ELEMENTS_INVENTORY.md

UI Elements Inventory - Storyteller RPG

Purpose: Comprehensive list of UI elements organized by page for design template generation
Date: October 12, 2025
Status: Phase 2 Complete, Planning Phase 3

---

🎨 Design System Overview

Color Palette

• Primary Gradient: #667eea to #764ba2 (purple gradient)
• Secondary Gradient: #ffd89b to #19547b (gold to teal)
• Background Dark: #1a1a2e, #16213e
• Surface Dark: #2d3748
• Text Light: #ffffff, #e2e8f0
• Text Muted: #a0aec0, #718096
• Accent: #667eea (purple)
• Success: #10b981, #34d399
• Warning: #f59e0b
• Error: #ef4444

Typography

• Font Family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif
• H1: 2.5rem, bold
• H2: 2rem, bold
• H3: 1.5rem, semibold
• Body: 1rem
• Small: 0.875rem

Spacing Scale

• xs: 0.25rem (4px)
• sm: 0.5rem (8px)
• md: 1rem (16px)
• lg: 1.5rem (24px)
• xl: 2rem (32px)
• 2xl: 3rem (48px)

Border Radius

• Small: 6px
• Medium: 8px
• Large: 12px
• XLarge: 20px

---

📄 Page 1: Session Setup / Landing Page

Purpose

Entry point for creating or joining game sessions

Layout Structure

┌─────────────────────────────────────┐
│         Header (Logo + Title)       │
├─────────────────────────────────────┤
│                                     │
│         Demo Session Cards          │
│                                     │
├─────────────────────────────────────┤
│                                     │
│     Create New Session Section      │
│                                     │
├─────────────────────────────────────┤
│                                     │
│    Join Existing Session Section    │
│                                     │
└─────────────────────────────────────┘

UI Elements

Header Section

• App Title: Large heading with emoji (🎭 Storyteller RPG)
• Subtitle: Descriptive tagline
• Logo/Icon: Optional app icon

Demo Section

• Section Title: "🎲 Demo Session - The Cursed Tavern"
• Description Text: Short description paragraph
• Button Group (3 buttons):
  • Storyteller button (🎲 icon, primary style)
  • Character 1 button (⚔️ icon, character style)
  • Character 2 button (🏹 icon, character style)
• Visual Style: Gradient background, rounded corners

Divider Elements

• Text Divider: "OR CREATE YOUR OWN" / "OR"
• Horizontal line with text overlay

Create Session Section

• Section Title: "Create New Session"
• Section Description: "Start a new game as the storyteller"
• Input Field: Text input for session name
• Primary Button: "Create Session" (full width)
• Visual Style: White card with shadow

Join Session Section

• Section Title: "Join Existing Session"
• Section Description: "Play as a character in an ongoing game"
• Form Elements:
  • Session ID input field
  • Character name input field
  • Character description textarea
  • Personality traits textarea (optional)
  • Model selector dropdown (grouped options)
  • Model hint text
• Action Buttons:
  • "✨ Create Character (Wizard)" - Primary gradient button
  • "↓ Quick Create" toggle - Secondary button
  • "Join Session (Simple)" - Conditional primary button
• Visual Style: White card with shadow

Responsive Behavior

• Desktop: Single column, max-width 600px, centered
• Mobile: Full width, stacked elements

---

📄 Page 2: Character View (Player Interface)

Purpose

Interface for players to interact with storyteller and view game state

Layout Structure

┌─────────────────────────────────────────────────┐
│  Character Header (Info + Status)               │
├─────────────────────────────────────────────────┤
│  Current Scene Card (if active)                 │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌─────────────────┬─────────────────────────┐ │
│  │ Public Messages │ Private Conversation    │ │
│  │ Feed            │ with Storyteller        │ │
│  │                 │                         │ │
│  │                 │                         │ │
│  └─────────────────┴─────────────────────────┘ │
│                                                 │
├─────────────────────────────────────────────────┤
│  Message Composer (Bottom)                      │
└─────────────────────────────────────────────────┘

UI Elements

Character Header

• Character Name: Large heading
• Character Description: Paragraph text
• Personality Trait: Small text with emoji (🎭)
• Profile Badges: 3 pill-shaped badges
  • Race badge
  • Class badge
  • Personality type badge
• Action Buttons:
  • Export button (📥 Export)
• Status Indicator: Connection status dot
  • Connected: Green dot + "● Connected"
  • Disconnected: Gray dot + "○ Disconnected"
• Visual Style: Dark gradient background, rounded top corners

Current Scene Card (Conditional)

• Section Title: "📜 Current Scene"
• Scene Text: Paragraph with scene description
• Visual Style: Highlighted card, distinct from messages

Public Messages Section

• Section Title: "📢 Public Actions (All Players See)"
• Message List:
  • Message bubble/card per public action
  • Sender indicator (🎭 Public Action / 🎲 Scene)
  • Message content
  • Timestamp (small, muted)
• Visual Style: Light background, left border accent

Private Conversation Section

• Section Title: "💬 Private Conversation with Storyteller"
• Message List:
  • Message bubbles alternating left/right
  • Character messages (right aligned, purple)
  • Storyteller messages (left aligned, different color)
  • Timestamps
• Scroll Behavior: Auto-scroll to bottom on new message

Message Composer (Bottom Section)

• Visibility Selector: Dropdown
  • Options: Private, Public, Mixed
• Mixed Mode Form:
  • Public textarea: "Public action (all players see)..."
  • Private textarea: "Private action (only storyteller sees)..."
  • Send button: "Send Mixed Message"
• Simple Mode Form:
  • Single input field (changes placeholder by visibility)
  • Send button
• Visual Style: Fixed to bottom, elevated shadow

Component States

• Connected State: Full functionality enabled
• Disconnected State: Inputs disabled, gray overlay
• Loading State: Skeleton screens
• Empty State: "No messages yet" placeholder

---

📄 Page 3: Character Creation Wizard

Purpose

Multi-step guided character creation with profile system

Layout Structure

┌─────────────────────────────────────────┐
│  Wizard Header (Title + Progress)       │
├─────────────────────────────────────────┤
│                                         │
│                                         │
│        Step Content Area                │
│        (Changes per step)               │
│                                         │
│                                         │
├─────────────────────────────────────────┤
│  Footer (Cancel | Back | Next/Create)  │
└─────────────────────────────────────────┘

UI Elements

Wizard Overlay

• Full-screen modal: Dark semi-transparent background
• Centered container: Max 800px width
• Visual Style: Dark gradient card with border

Wizard Header

• Title: "Create Your Character" (large heading)
• Progress Indicator: 6 steps
  • Step pills showing: "1. Basic Info", "2. Description", etc.
  • Active step highlighted
  • Completed steps dimmed
  • Responsive: Wraps on mobile

Step 1: Basic Info

• Step Title: "Basic Information"
• Input Fields:
  • Character name (text input, required, autofocus)
  • Gender dropdown (4 options)
• Import Section:
  • Import hint text: "💡 Have an existing character?"
  • File upload button: "📥 Import from JSON"
  • Hidden file input (accepts .json)
• Visual Style: Form inputs with dark theme

Step 2: Description

• Step Title: "Character Description"
• Input Fields:
  • Description textarea (required, 4 rows)
  • Background textarea (optional, 3 rows)
• Visual Style: Larger text areas, clear labels

Step 3: Race & Class

• Step Title: "Race & Class"
• Race Selection:
  • Label: "Race"
  • Selection grid (responsive, min 200px cards)
  • 5 clickable cards:
    • Race name (bold)
    • Race description (smaller text)
    • Selected state: gradient background + border
    • Hover state: slight elevation
• Class Selection:
  • Same layout as Race
  • 5 class cards
• Visual Style: Grid layout, interactive cards

Step 4: Personality

• Step Title: "Personality Type"
• Selection Grid:
  • 4 personality type cards
  • Same card style as race/class
• Additional Input:
  • "Additional Personality Traits" textarea (optional, 3 rows)
• Visual Style: Consistent with Step 3

Step 5: AI Model

• Step Title: "AI Model Selection"
• Model Dropdown:
  • Large dropdown (bigger padding/font)
  • Grouped options (OpenAI / OpenRouter)
  • Shows provider in parentheses
• Help Text:
  • "💡 Different models give different personalities!"
  • Multi-line hint text
• Visual Style: Prominent dropdown, informative hint

Step 6: Review

• Step Title: "Review Your Character"
• Preview Card:
  • Multiple sections with borders between:
    • Basic Information (name, gender, race, class, personality)
    • Description
    • Background (if provided)
    • Additional Traits (if provided)
    • AI Model
  • Summary box at bottom:
    • Highlighted background
    • "Character Summary" heading
    • Natural language summary sentence
• Visual Style: Clean, organized, easy to scan

Wizard Footer

• Button Layout:
  • Cancel (left, secondary)
  • Navigation (right):
    • Back button (steps 2-6, secondary)
    • Next button (steps 1-5, primary)
    • Create button (step 6, primary with sparkles)
• Visual Style: Fixed footer, clear hierarchy

Animation & Transitions

• Step Changes: Fade in with slight upward movement
• Card Selection: Transform scale + shadow on selection
• Button Hovers: Slight elevation, color shift
• Progress Indicator: Smooth transitions between steps

---

📄 Page 4: Storyteller View

Purpose

Interface for storyteller to manage game, view all character actions, and respond

Layout Structure

┌──────────────────────────────────────────────────┐
│  Header (Session Info + Controls)                │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌───────────────┬────────────────────────────┐ │
│  │ Character     │ Main Content Area:         │ │
│  │ List          │                            │ │
│  │ (Sidebar)     │ - Public Actions Feed      │ │
│  │               │ - Selected Character View  │ │
│  │               │ - Scene Narration          │ │
│  │               │                            │ │
│  └───────────────┴────────────────────────────┘ │
│                                                  │
└──────────────────────────────────────────────────┘

UI Elements

Storyteller Header

• Session Name: Large heading
• Session ID: Copy button with ID
• Control Buttons:
  • Generate contextual response button
  • Other session controls
• Visual Style: Dark header, elevated

Character List Sidebar

• Section Title: "Characters in Session"
• Character Cards: (One per character)
  • Character name
  • Race/Class/Personality badges
  • "Needs Response" indicator (conditional)
  • Click to select
  • Active state highlighting
• Empty State: "No characters yet" message
• Visual Style: Scrollable sidebar, clear selection state

Public Actions Feed

• Section Title: "📢 Recent Public Actions"
• Feed Items:
  • Character name/avatar
  • Public action text
  • Timestamp
  • Compact card style
• Visual Style: Timeline/feed layout

Character Conversation View

• Character Header:
  • Selected character name
  • Profile info
• Conversation Thread:
  • Message list (character + storyteller messages)
  • Clear visual distinction between senders
  • Timestamps
• Response Composer:
  • Textarea for response
  • "✨ AI Suggest" button
  • "Send Private Response" button
• Visual Style: Similar to character view but reversed perspective

AI Suggestion Modal/Section

• Generated Response Display:
  • Title: "AI-Generated Suggestion"
  • Response content (editable)
  • Model used indicator
• Action Buttons:
  • "Use This Response"
  • "Regenerate"
  • "Cancel"
• Visual Style: Highlighted section, easy to edit

Scene Narration Section

• Section Title: "Broadcast Scene to All Players"
• Input Field:
  • Large textarea for scene description
  • Character count/hint
• Contextual Generation:
  • "Generate with AI" button
  • Character selection checkboxes
  • Additional context input
• Send Button: "📜 Broadcast Scene"
• Visual Style: Prominent, distinct from private responses

Responsive Behavior

• Desktop: Sidebar + main content (grid layout)
• Tablet: Collapsible sidebar
• Mobile: Stack vertically, tab navigation

---

📄 Page 5: Gamemaster Control Panel (Phase 3)

Purpose

Admin interface to create games, assign roles, and manage session

Layout Structure

┌────────────────────────────────────────────┐
│  GM Header (Game Info + Quick Actions)     │
├────────────────────────────────────────────┤
│                                            │
│  ┌──────────────┬──────────────────────┐  │
│  │ Game         │ Main Panel:          │  │
│  │ Sessions     │                      │  │
│  │ List         │ - Game Setup Wizard  │  │
│  │              │ - Role Assignment    │  │
│  │              │ - Player Management  │  │
│  │              │ - Game State View    │  │
│  │              │                      │  │
│  └──────────────┴──────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘

UI Elements

GM Dashboard Header

• Title: "Gamemaster Control Panel"
• Active Game Indicator: Current game name
• Quick Actions:
  • "Create New Game" button
  • "Load Game" button
  • "Save Game" button
• Visual Style: Command center aesthetic

Game Sessions List

• List Items: (Per game)
  • Game name
  • Status badge (not started, active, paused, completed)
  • Player count
  • Created date
  • Actions: View, Edit, Delete
• Visual Style: Card list, status colors

Game Creation Wizard

• Step 1: Game Info
  • Game name input
  • Scenario/setting textarea
  • Genre/theme selector
• Step 2: Player Slots
  • Slot configuration (number input)
  • Slot cards:
    • Slot type (Human/AI toggle)
    • Player assignment (if human)
    • AI configuration (if AI)
• Step 3: Storyteller Assignment
  • Radio buttons: Human / AI
  • User selector (if human)
  • AI model selector (if AI)
  • Storytelling style dropdown
• Step 4: Game Settings
  • Turn-based toggle
  • Auto-save interval
  • Other game rules
• Visual Style: Multi-step wizard like character creation

Role Assignment Interface

• Player Slots Grid:
  • Drag-and-drop cards
  • Each slot shows:
    • Slot number
    • Assigned player/AI
    • Character info (if selected)
    • Edit button
• Available Players Panel:
  • List of users
  • Drag to assign
• Visual Style: Interactive, clear assignment state

Game State Overview

• Tabs:
  • Overview
  • Characters
  • Messages
  • Timeline
• Overview Tab:
  • Game status
  • Current scene
  • Active players
  • Statistics (messages, actions, etc.)
• Characters Tab:
  • All character profiles
  • Stats/inventory (if applicable)
• Messages Tab:
  • All messages (public + private)
  • Filter controls
• Visual Style: Dashboard with data cards

AI Storyteller Command Interface

• Command Input:
  • Special input for GM → AI storyteller
  • Examples: "Introduce a plot twist", "Increase difficulty"
• AI Status:
  • Active/paused toggle
  • Last action timestamp
  • Response queue
• Override Controls:
  • Edit AI responses
  • Take manual control
• Visual Style: Distinct command interface

---

📄 Page 6: Admin Dashboard (Development/Future)

Purpose

System-wide administration, monitoring, and configuration

Layout Structure

┌────────────────────────────────────────┐
│  Admin Header (System Status)          │
├────────────────────────────────────────┤
│                                        │
│  ┌──────────┬──────────────────────┐  │
│  │ Nav Menu │ Content Panel        │  │
│  │          │                      │  │
│  │ - Games  │ (Changes per menu)   │  │
│  │ - Users  │                      │  │
│  │ - Models │                      │  │
│  │ - Costs  │                      │  │
│  │ - Logs   │                      │  │
│  │          │                      │  │
│  └──────────┴──────────────────────┘  │
│                                        │
└────────────────────────────────────────┘

UI Elements

Admin Header

• Title: "System Administration"
• System Status Indicators:
  • API status (green/red dot)
  • Active games count
  • Active users count
• Visual Style: Dark header, status indicators

Navigation Menu

• Menu Items:
  • Dashboard (overview)
  • Games Management
  • User Management
  • LLM Configuration
  • Cost Analytics
  • System Logs
  • Settings
• Visual Style: Vertical menu, active state highlighting

Dashboard Overview

• Metric Cards:
  • Total games (number + trend)
  • Total users (number + trend)
  • API calls today (number + cost)
  • System health (percentage)
• Recent Activity Feed:
  • Latest games created
  • Recent errors
  • High-cost requests
• Charts:
  • Games over time
  • Cost over time
  • Model usage distribution
• Visual Style: Grid of cards, charts with tooltips

Games Management

• Games Table:
  • Columns: ID, Name, GM, Players, Status, Created, Actions
  • Sort controls
  • Filter controls
  • Pagination
• Actions:
  • View details
  • Force end
  • Delete
• Visual Style: Data table with actions

User Management

• Users Table:
  • Columns: Username, Email, Role, Games, Joined, Status, Actions
  • Search bar
  • Role filter
• Actions:
  • Edit role
  • Suspend/activate
  • View activity
• Visual Style: Data table with user cards

LLM Configuration

• Model Cards: (Per model)
  • Model name
  • Provider
  • Status (enabled/disabled toggle)
  • Usage stats
  • Cost per token
  • Edit button
• Add Model Form:
  • Model ID input
  • API key input
  • Configuration options
• Visual Style: Grid of model cards

Cost Analytics

• Summary Cards:
  • Total cost this month
  • Average per game
  • Most expensive model
• Cost Breakdown:
  • Per model chart
  • Per game table
  • Per user table
• Date Range Selector:
  • Preset ranges (Today, Week, Month)
  • Custom range picker
• Export Button: Download CSV
• Visual Style: Charts and tables

System Logs

• Log Viewer:
  • Real-time log stream
  • Log level filter (Info, Warning, Error)
  • Search/filter input
  • Timestamp
  • Auto-scroll toggle
• Visual Style: Terminal/console aesthetic

---

🎯 Common UI Components (Used Across Pages)

Buttons

• Primary Button:
  • Gradient background (#667eea to #764ba2)
  • White text, rounded corners
  • Hover: Slight lift, darker gradient
  • Sizes: Small, Medium, Large
• Secondary Button:
  • Transparent/outlined style
  • Border color matches theme
  • Hover: Background color change
• Icon Buttons:
  • Circular or square
  • Icon only, tooltip on hover
• Danger Button:
  • Red color scheme
  • Used for delete/destructive actions

Input Fields

• Text Input:
  • Dark background with light border
  • Focus: Border color change, glow effect
  • Error state: Red border + error message below
  • Success state: Green border
• Textarea:
  • Same as text input but multi-line
  • Resize handle
• Dropdown/Select:
  • Custom styled select
  • Grouped options support
  • Search/filter (for long lists)
• Checkbox:
  • Custom checkbox with checkmark animation
  • Label click support
• Radio Buttons:
  • Custom styled radio
  • Clear selected state
• File Upload:
  • Drag-and-drop zone
  • File type indicator
  • Upload progress

Cards

• Base Card:
  • Rounded corners (8-12px)
  • Shadow for elevation
  • Padding: 1-2rem
  • Background: White or dark surface
• Interactive Card:
  • Hover state: Lift effect
  • Click state: Scale slightly
  • Selection state: Border highlight
• Info Card:
  • Icon + title + content
  • Color-coded by type

Badges/Pills

• Status Badge:
  • Small, rounded pill
  • Color-coded (green=active, red=error, yellow=warning)
  • Sizes: XS, SM, MD
• Count Badge:
  • Circular badge with number
  • Often overlays buttons/icons

Modals/Overlays

• Modal:
  • Full-screen semi-transparent overlay
  • Centered content container
  • Close button (X) in top-right
  • Click outside to close (optional)
• Toast/Notification:
  • Slide in from top-right
  • Auto-dismiss after timeout
  • Close button
  • Type: Success, Error, Warning, Info

Navigation

• Tabs:
  • Horizontal tabs with active state
  • Underline or background highlight
• Breadcrumbs:
  • Path navigation
  • Separator (/ or >)
  • Click to navigate
• Pagination:
  • Previous/Next buttons
  • Page numbers
  • Jump to page input

Loading States

• Spinner:
  • Circular spinner (small, medium, large)
  • Themed color
• Skeleton Screen:
  • Gray placeholder boxes
  • Shimmer animation
• Progress Bar:
  • Linear progress indicator
  • Percentage display (optional)

Empty States

• No Data:
  • Icon + message
  • Call-to-action button
  • Helpful hint text
• Error State:
  • Error icon + message
  • Retry button
  • Support link

---

📱 Responsive Breakpoints

Desktop (1024px+)

• Multi-column layouts
• Sidebars visible
• Full navigation

Tablet (768px - 1023px)

• Collapsible sidebars
• Stacked cards
• Simplified navigation

Mobile (<768px)

• Single column
• Bottom navigation
• Hamburger menu
• Full-screen modals
• Larger tap targets

---

♿ Accessibility Requirements

Keyboard Navigation

• All interactive elements focusable
• Logical tab order
• Focus indicators (outline)
• Keyboard shortcuts (optional)

Screen Reader Support

• Semantic HTML
• ARIA labels where needed
• Alt text for images
• Form labels associated

Color Contrast

• WCAG AA minimum (4.5:1 for text)
• Color not sole indicator
• High contrast mode support

Interaction

• Minimum touch target: 44x44px
• No timing-critical interactions
• Error prevention and recovery

---

🎨 Animation Guidelines

Durations

• Micro: 100-200ms (hover, focus)
• Short: 200-300ms (buttons, tooltips)
• Medium: 300-500ms (modals, page transitions)
• Long: 500-800ms (complex animations)

Easing

• Ease-out: UI appearing (modal open)
• Ease-in: UI disappearing (modal close)
• Ease-in-out: Smooth transitions

Motion Preferences

• Respect prefers-reduced-motion
• Disable decorative animations
• Keep functional animations

---

📐 Layout Patterns

Container Widths

• Max Width: 1200px (main content)
• Narrow: 600px (forms, wizards)
• Wide: 1400px (dashboards)

Grid Systems

• 12-column grid for complex layouts
• Flexbox for simple layouts
• CSS Grid for card grids

Spacing Rhythm

• Consistent vertical rhythm (8px base unit)
• Component spacing: 16px, 24px, 32px
• Section spacing: 48px, 64px

---

🎯 Priority Elements for UI Design Templates

High Priority (MVP Essential)

1. Session Setup page
2. Character View
3. Character Creation Wizard
4. Storyteller View
5. Primary buttons and inputs

Medium Priority (Phase 3)

6. Gamemaster Control Panel
7. Role assignment interface
8. Game state dashboard

Low Priority (Future)

9. Admin Dashboard
10. Analytics views
11. Advanced settings

---

Use this document to prompt UI design tools with specific page requirements!

Example prompt structure:

Create a modern dark-themed UI design for [PAGE NAME] with the following elements:
[List specific elements from above]
Color scheme: Purple gradient (#667eea to #764ba2)
Style: Modern, RPG-themed, clean