# 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
```