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! 🎨