aodhan/storyteller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 2 complete

Browse Source
This commit is contained in:
Aodhan Collins
2025-10-12 02:18:56 +01:00
parent da30107f5b
commit 41975ecfe2
13 changed files with 3904 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

890
docs/reference/UI_ELEMENTS_INVENTORY.md Normal file
View File

@@ -0,0 +1,890 @@
# 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
```