docs/WEB_UI_VISUAL_GUIDE.md

# Web UI Visual Guide

## Interface Layout

```
╔════════════════════════════════════════════════════════════════════════════╗
║                  🏙️ AI Personas for Urban Planning                         ║
║          Explore diverse stakeholder perspectives on urban planning        ║
╠════════════════════════════════════════╦═══════════════════════════════════╣
║                                        ║     👥 Select a Persona           ║
║  💬 Conversation                       ║     Click to start conversation   ║
║  ┌────────────────────────────────┐   ║                                   ║
║  │ Currently talking with:        │   ║   ┌─────────────────────────┐   ║
║  │ 🌱 Sarah Chen (Urban Planner)  │   ║   │         🌱                │   ║
║  └────────────────────────────────┘   ║   │    Sarah Chen            │   ║
║                                        ║   │   Urban Planner          │   ║
║  ┌────────────────────────────────┐   ║   │Progressive, sustainability│   ║
║  │ Your question: ________________│   ║   └─────────────────────────┘   ║
║  │                         [Send] │   ║                                   ║
║  └────────────────────────────────┘   ║   ┌─────────────────────────┐   ║
║                                        ║   │         🏪                │   ║
║  💡 Try asking:                        ║   │   Marcus Thompson        │   ║
║  ┌──────────────────┐ ┌─────────────┐ ║   │   Business Owner         │   ║
║  │ What's most      │ │ Should we   │ ║   │ Pragmatic, economy-first │   ║
║  │ important issue? │ │ allow food  │ ║   └─────────────────────────┘   ║
║  └──────────────────┘ └─────────────┘ ║                                   ║
║  ┌──────────────────┐ ┌─────────────┐ ║   ┌─────────────────────────┐   ║
║  │ How to make city │ │ Affordable  │ ║   │         🚇                │   ║
║  │ sustainable?     │ │ housing?    │ ║   │  Dr. Elena Rodriguez     │   ║
║  └──────────────────┘ └─────────────┘ ║   │Transportation Engineer   │   ║
║                                        ║   │ Data-driven, safety-first│   ║
║  ─────────────────────────────────     ║   └─────────────────────────┘   ║
║                                        ║                                   ║
║  📜 Conversation History               ║   ┌─────────────────────────┐   ║
║                                        ║   │         🏡                │   ║
║  ┌────────────────────────────────┐   ║   │    James O'Brien         │   ║
║  │ 🙋 You:                        │   ║   │   Long-time Resident     │   ║
║  │ What do you think about the    │   ║   │Traditional, community-   │   ║
║  │ bike lane proposal?            │   ║   │      focused             │   ║
║  └────────────────────────────────┘   ║   └─────────────────────────┘   ║
║                                        ║                                   ║
║  ┌────────────────────────────────┐   ║   ┌─────────────────────────┐   ║
║  │ 🌱 Sarah Chen:                 │   ║   │         ✊                │   ║
║  │ I strongly support this bike   │   ║   │     Priya Patel          │   ║
║  │ lane proposal. As an urban     │   ║   │   Housing Advocate       │   ║
║  │ planner focused on             │   ║   │ Activist, equity-focused │   ║
║  │ sustainability, I believe this │   ║   └─────────────────────────┘   ║
║  │ aligns perfectly with our      │   ║                                   ║
║  │ climate goals. The data shows  │   ║   ┌─────────────────────────┐   ║
║  │ protected bike lanes reduce... │   ║   │         🏢                │   ║
║  └────────────────────────────────┘   ║   │      David Kim           │   ║
║                                        ║   │ Real Estate Developer    │   ║
║  ┌────────────────────────────────┐   ║   │Market-driven, growth-    │   ║
║  │ 🗑️ Clear Conversation          │   ║   │      oriented            │   ║
║  └────────────────────────────────┘   ║   └─────────────────────────┘   ║
║                                        ║                                   ║
╠════════════════════════════════════════╩═══════════════════════════════════╣
║  AI Personas • Phase 1 • Powered by Claude 3 Haiku • View Code            ║
╚════════════════════════════════════════════════════════════════════════════╝
```

## Key Features Illustrated

### 1. Persona Cards (Right Panel)

Each persona card shows:
- **Avatar emoji** - Visual identifier (🌱 🏪 🚇 🏡 ✊ 🏢)
- **Name** - Full name of the persona
- **Role** - Their professional or community role
- **Tagline** - Brief description of their perspective

**Selected State:**
- Cards highlight when selected (blue border)
- Button turns to "primary" style
- Name appears in conversation header

### 2. Conversation Area (Left Panel - Top)

**Currently Talking With Banner:**
```
┌────────────────────────────────┐
│ Currently talking with:        │
│ 🌱 Sarah Chen (Urban Planner)  │
└────────────────────────────────┘
```
Shows who you're conversing with.

**Question Input:**
```
┌────────────────────────────────┐
│ Your question: [Type here...] │
│                        [Send]  │
└────────────────────────────────┘
```
- Text input field for questions
- Placeholder text guides the user
- Send button to submit

### 3. Quick Suggestions (Left Panel - Middle)

```
💡 Try asking:
┌──────────────────┐ ┌─────────────┐
│ What's most      │ │ Should we   │
│ important issue? │ │ allow food  │
└──────────────────┘ └─────────────┘
```

Four pre-written questions to get started:
- Click any button to auto-fill the question
- Helpful for first-time users
- Demonstrates good question types

### 4. Conversation History (Left Panel - Bottom)

**User Messages (Blue):**
```
┌────────────────────────────────┐
│ 🙋 You:                        │
│ What do you think about the    │
│ bike lane proposal?            │
└────────────────────────────────┘
```

**Persona Responses (Gray):**
```
┌────────────────────────────────┐
│ 🌱 Sarah Chen:                 │
│ I strongly support this bike   │
│ lane proposal...               │
└────────────────────────────────┘
```

**Clear Button:**
```
┌────────────────────────────────┐
│ 🗑️ Clear Conversation          │
└────────────────────────────────┘
```
Resets the conversation for a fresh start.

## User Flow

### First Visit

```
1. User lands on page
   ↓
2. Sees 6 persona cards on right
   ↓
3. Sees "Select a persona" message on left
   ↓
4. Clicks on a persona (e.g., Sarah Chen)
   ↓
5. Persona card highlights
   ↓
6. Left panel shows "Currently talking with Sarah Chen"
   ↓
7. User sees quick suggestions
   ↓
8. Clicks suggestion or types question
   ↓
9. Clicks Send button
   ↓
10. "💭 Sarah Chen is thinking..." appears
    ↓
11. Response appears in conversation history
    ↓
12. User can ask follow-up or switch persona
```

### Switching Personas

```
1. User clicks different persona (e.g., Marcus)
   ↓
2. Previous persona card unhighlights
   ↓
3. New persona card highlights
   ↓
4. Conversation history clears
   ↓
5. Banner updates to show Marcus Thompson
   ↓
6. User can start new conversation
```

## Color Coding

Each persona has a unique color theme:

- **🌱 Sarah Chen**: Green (#4CAF50) - Sustainability
- **🏪 Marcus Thompson**: Orange (#FF9800) - Business/Commerce
- **🚇 Elena Rodriguez**: Blue (#2196F3) - Technical/Engineering
- **🏡 James O'Brien**: Brown (#795548) - Traditional/Established
- **✊ Priya Patel**: Pink (#E91E63) - Activism/Energy
- **🏢 David Kim**: Gray (#607D8B) - Professional/Corporate

## Responsive Design

### Desktop (Wide Screen)
```
┌─────────────────────────┬───────────┐
│                         │  Personas │
│    Conversation         │   Cards   │
│      (2/3 width)        │ (1/3 width)│
└─────────────────────────┴───────────┘
```

### Tablet (Medium Screen)
```
┌─────────────────────────┬─────┐
│                         │ P   │
│    Conversation         │ e   │
│                         │ r   │
│                         │ s   │
└─────────────────────────┴─────┘
```

### Mobile (Narrow Screen)
```
┌───────────────┐
│ Conversation  │
│               │
└───────────────┘
┌───────────────┐
│ Persona Cards │
│ (Stacked)     │
└───────────────┘
```

## Interactive Elements

### Buttons

**Persona Selection Buttons:**
- Hover: Slight lift effect (translateY)
- Selected: Primary color, bold border
- Unselected: Secondary color, subtle border

**Send Button:**
- Full width of container
- Primary color
- Bold text
- 3rem height for easy clicking

**Suggestion Buttons:**
- Two columns layout
- Full width of container
- Secondary color
- Fills input when clicked

**Clear Conversation:**
- Full width
- Warning/destructive action style
- Icon + text label

### Input Field

**Text Input:**
- Placeholder: "e.g., What do you think about..."
- Auto-focus when page loads
- Enter key submits
- Clears after sending

### Loading States

**Thinking Indicator:**
```
💭 Sarah Chen is thinking...
```
Shows while waiting for API response.

**System Initialization:**
```
🔧 Initializing AI Personas system...
```
Shows on first page load.

## Accessibility Features

- **Keyboard Navigation**: Tab through all interactive elements
- **Screen Reader Support**: Semantic HTML with ARIA labels
- **High Contrast**: Text meets WCAG AA standards
- **Focus Indicators**: Visible keyboard focus states
- **Clear Labels**: All buttons have descriptive text

## Tips for Best Experience

### 1. Large Screen Recommended
- Best viewed on desktop or tablet (≥1024px width)
- Mobile works but cards may stack vertically

### 2. Modern Browser
- Chrome, Firefox, Safari, Edge (recent versions)
- JavaScript must be enabled

### 3. Stable Internet
- Responses require API calls
- 2-5 seconds per response

### 4. Clear Conversation
- Click "Clear Conversation" before switching topics
- Or switch personas for fresh start

## Comparison: CLI vs. Web UI

| Feature | CLI (`src.cli`) | Web UI (`web_app.py`) |
|---------|-----------------|----------------------|
| **Visual** | Text-only | Rich visual interface |
| **Personas** | Text list | Emoji avatars + cards |
| **History** | Scrolling text | Formatted chat boxes |
| **Input** | Command prompt | Text field with Send button |
| **Suggestions** | None | Quick-click buttons |
| **Selection** | Type persona ID | Click card |
| **Mobile** | Terminal only | Web browser |
| **Learning curve** | Higher | Lower |
| **Power user** | Better for scripts | Better for exploration |

## Future Enhancements

Planned improvements:
- [ ] Export conversation to PDF
- [ ] Dark mode toggle
- [ ] Voice input/output
- [ ] Multi-persona comparison (split view)
- [ ] Conversation templates
- [ ] Mobile app version
- [ ] Real-time typing indicators
- [ ] Emoji reactions to responses
- [ ] Save/load conversations
- [ ] Share conversation links

---

**The Web UI makes exploring personas intuitive, visual, and engaging! 🎨**