# 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** ✅