---
name: Modern AI Chat UI Design
overview: "Comprehensive UI/UX design plan for modern AI chat interfaces with two web applications: Web Client (user-facing chat interface) and Web Admin (admin dashboard). Includes complete design system, component library, responsive design, accessibility, and implementation phases with 60+ granular todos for multi-agent parallel development."
todos:
  - id: design-system-1
    content: "[Agent 1] Initialize Tailwind CSS 4 in web-client with custom configuration"
    status: completed
  - id: design-system-2
    content: "[Agent 1] Create CSS variables file (src/styles/theme.css) with all color, typography, spacing, and animation tokens"
    status: completed
  - id: design-system-3
    content: "[Agent 2] Build Button component (src/components/ui/button.tsx) with variants (primary, secondary, ghost, danger) and sizes (xs, sm, md, lg, xl)"
    status: completed
  - id: design-system-4
    content: "[Agent 2] Build Input component (src/components/ui/input.tsx) with validation states (default, focus, error, success, disabled)"
    status: completed
  - id: design-system-5
    content: "[Agent 3] Build Card component (src/components/ui/card.tsx) with subcomponents (CardHeader, CardTitle, CardDescription, CardContent, CardFooter)"
    status: completed
  - id: design-system-6
    content: "[Agent 3] Build Modal/Dialog component (src/components/ui/dialog.tsx) using Radix UI with overlay and content animations"
    status: completed
  - id: design-system-7
    content: "[Agent 3] Build Avatar component (src/components/ui/avatar.tsx) with sizes (xs, sm, md, lg, xl) and status indicators"
    status: completed
  - id: design-system-8
    content: "[Agent 4] Setup theme switching system (dark/light mode) with Context API and localStorage persistence"
    status: completed
  - id: design-system-9
    content: "[Agent 4] Initialize Storybook for component documentation and visual testing"
    status: completed
  - id: auth-1
    content: "[Agent 1] Create Login page (src/app/(auth)/login/page.tsx) with email/password inputs, validation, and error handling"
    status: completed
  - id: auth-2
    content: "[Agent 1] Create Register page (src/app/(auth)/register/page.tsx) with password strength indicator and form validation"
    status: completed
  - id: auth-3
    content: "[Agent 2] Implement Forgot Password flow (src/app/(auth)/forgot-password/page.tsx) with email input and reset link"
    status: completed
  - id: auth-4
    content: "[Agent 3] Integrate OAuth with Google (src/lib/auth/oauth.ts) using NextAuth or similar library"
    status: completed
  - id: auth-5
    content: "[Agent 4] Create auth store (src/stores/auth-store.ts) with Zustand for managing authentication state"
    status: completed
  - id: chat-1
    content: "[Agent 1] Build Chat layout component (src/components/chat/chat-layout.tsx) with sidebar, main area, and optional right panel"
    status: completed
  - id: chat-2
    content: "[Agent 1] Build MessageBubble component (src/components/chat/message-bubble.tsx) with user/AI variants and message actions"
    status: completed
  - id: chat-3
    content: "[Agent 2] Build ChatInput component (src/components/chat/chat-input.tsx) with auto-resize textarea and send button"
    status: completed
  - id: chat-4
    content: "[Agent 2] Build TypingIndicator component (src/components/chat/typing-indicator.tsx) with pulsing dots animation"
    status: completed
  - id: chat-5
    content: "[Agent 3] Build ConversationSidebar component (src/components/chat/conversation-sidebar.tsx) with search and conversation list"
    status: completed
  - id: chat-6
    content: "[Agent 3] Implement message actions menu (copy, edit, delete, regenerate, like/dislike, share) on message hover"
    status: completed
  - id: chat-7
    content: "[Agent 4] Integrate WebSocket client (src/lib/websocket.ts) for real-time messaging with reconnection logic"
    status: completed
  - id: chat-8
    content: "[Agent 4] Create chat store (src/stores/chat-store.ts) with Zustand for managing messages and conversation state"
    status: completed
  - id: settings-1
    content: "[Agent 1] Create User Profile page (src/app/(dashboard)/settings/profile/page.tsx) with avatar upload and profile fields"
    status: completed
  - id: settings-2
    content: "[Agent 1] Create Settings layout (src/app/(dashboard)/settings/layout.tsx) with tab navigation (Profile, Preferences, Security, etc.)"
    status: completed
  - id: settings-3
    content: "[Agent 2] Implement Preferences tab (src/app/(dashboard)/settings/preferences/page.tsx) with language, theme, chat settings, and accessibility options"
    status: completed
  - id: settings-4
    content: "[Agent 3] Implement Security tab (src/app/(dashboard)/settings/security/page.tsx) with password change, 2FA setup (QR code), and active sessions"
    status: completed
  - id: settings-5
    content: "[Agent 4] Implement API Keys management page (src/app/(dashboard)/settings/api-keys/page.tsx) for developers"
    status: completed
  - id: admin-1
    content: "[Agent 1] Create Admin Dashboard layout (apps/web-admin/src/app/(dashboard)/layout.tsx) with sidebar navigation"
    status: completed
  - id: admin-2
    content: "[Agent 1] Build AnalyticsCard component (apps/web-admin/src/components/admin/analytics-card.tsx) with metric, chart, progress, and comparison variants"
    status: completed
  - id: admin-3
    content: "[Agent 1] Create Dashboard overview page (apps/web-admin/src/app/(dashboard)/dashboard/page.tsx) with metrics row and charts"
    status: completed
  - id: admin-4
    content: "[Agent 2] Integrate Recharts and create UserGrowthChart component (apps/web-admin/src/components/admin/charts/user-growth-chart.tsx)"
    status: completed
  - id: admin-5
    content: "[Agent 3] Create RevenueChart component (apps/web-admin/src/components/admin/charts/revenue-chart.tsx) as Area Chart"
    status: completed
  - id: admin-6
    content: "[Agent 4] Build RecentActivityTable component (apps/web-admin/src/components/admin/recent-activity-table.tsx) with pagination"
    status: completed
  - id: admin-7
    content: "[Agent 1] Create UserManagement page (apps/web-admin/src/app/(dashboard)/users/page.tsx) with search and filters"
    status: completed
  - id: admin-8
    content: "[Agent 1] Build DataTable component (apps/web-admin/src/components/admin/data-table.tsx) with sorting, filtering, pagination, and bulk actions"
    status: completed
  - id: admin-9
    content: "[Agent 2] Create UserDetailsModal component (apps/web-admin/src/components/admin/user-details-modal.tsx) with profile, activity timeline, and message history"
    status: completed
  - id: admin-10
    content: "[Agent 3] Implement bulk actions for users (activate, deactivate, delete) with confirmation dialogs"
    status: completed
  - id: admin-11
    content: "[Agent 1] Create SystemSettings page (apps/web-admin/src/app/(dashboard)/settings/page.tsx) with tabs (General, Email, Security, API, Advanced)"
    status: completed
  - id: admin-12
    content: "[Agent 1] Build GeneralSettings form (apps/web-admin/src/components/admin/settings/general-settings.tsx) with site name, logo, language, timezone, maintenance mode"
    status: completed
  - id: admin-13
    content: "[Agent 2] Build EmailSettings form (apps/web-admin/src/components/admin/settings/email-settings.tsx) with SMTP configuration, email templates, and test email function"
    status: completed
  - id: admin-14
    content: "[Agent 3] Build SecuritySettings form (apps/web-admin/src/components/admin/settings/security-settings.tsx) with password policy, session timeout, IP whitelist/blacklist, rate limiting, CORS"
    status: completed
  - id: responsive-1
    content: "[Agent 1] Mobile responsive for web-client: Hide sidebar by default, full-width messages, sticky header/input, swipe gestures"
    status: completed
  - id: responsive-2
    content: "[Agent 2] Mobile responsive for web-admin: Collapsible sidebar, stacked metric cards, horizontal scroll tables, touch-friendly buttons (44px min)"
    status: completed
  - id: responsive-3
    content: "[Agent 2] Tablet optimizations: Two-column layout, show sidebar (toggleable), medium-width messages (60%), side-by-side charts"
    status: completed
  - id: responsive-4
    content: "[Agent 2] Touch-friendly interactions: 44px minimum touch targets, 8px spacing between, active state feedback, swipe gestures (left/right, pull down, long press)"
    status: completed
  - id: accessibility-1
    content: "[Agent 3] Keyboard navigation: Focus indicators (2px solid outline), logical tab order, custom shortcuts (Ctrl+K for search, Ctrl+N for new chat, etc.)"
    status: completed
  - id: accessibility-2
    content: "[Agent 3] ARIA labels and semantic HTML: Proper HTML5 elements (header, nav, main, aside, footer), descriptive aria-labels for all interactive elements, form validation with aria-invalid and aria-describedby"
    status: completed
  - id: accessibility-3
    content: "[Agent 4] Screen reader support: Live regions for announcements (role=\"status\" aria-live=\"polite\"), proper labels for all inputs, skip to main content link"
    status: completed
  - id: accessibility-4
    content: "[Agent 4] WCAG 2.1 AA compliance verification: Color contrast testing (4.5:1 for normal text, 3:1 for large text), font size minimum 16px, zoom support up to 200%, alternative text for all images"
    status: completed
  - id: performance-1
    content: "[Agent 1] Code splitting implementation: Route-based splitting with React.lazy, component-based splitting for heavy components (charts, modals), dynamic imports"
    status: completed
  - id: performance-2
    content: "[Agent 2] Image optimization: Next.js Image component with WebP/AVIF formats, responsive images (srcset), blur placeholder, lazy loading"
    status: completed
  - id: performance-3
    content: "[Agent 1] Lazy loading: Components (React.lazy), images (loading=\"lazy\"), routes (dynamic imports), heavy libraries (charts, animations)"
    status: completed
  - id: performance-4
    content: "[Agent 3] Caching strategy: Browser caching for static assets (1 year), API response caching with React Query, service worker for offline support, session storage for user data"
    status: completed
  - id: performance-5
    content: "[Agent 4] Lighthouse optimization: Target scores (Performance 90+, Accessibility 95+, Best Practices 95+, SEO 100), Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)"
    status: completed
  - id: testing-1
    content: "[Agent 1] Unit tests for UI components: Jest + React Testing Library, test Button, Input, Card, Dialog, Avatar components with all variants and states"
    status: completed
  - id: testing-2
    content: "[Agent 2] Unit tests for hooks and stores: Test useChat, useAuth, useTheme hooks, test Zustand stores (auth-store, chat-store, theme-store)"
    status: completed
  - id: testing-3
    content: "[Agent 3] E2E tests for critical flows: Login/Register flow, Chat message sending, Settings updates, Admin user management (using Playwright or Cypress)"
    status: completed
  - id: testing-4
    content: "[Agent 4] Cross-browser testing: Test on Chrome, Firefox, Safari, Edge, verify responsive layouts, check for visual regressions"
    status: completed
  - id: testing-5
    content: "[Agent 4] Performance testing: Lighthouse CI, WebPageTest, monitor Core Web Vitals, test on slow 3G connection"
    status: completed
  - id: testing-6
    content: "[Agent 5] Bug fixes and polish: Fix animation issues, improve micro-interactions, handle edge cases, optimize bundle size, final UI polish"
    status: completed
---

# Modern AI Chat UI Design - Implementation Plan

## Tổng quan kiến trúc UI

Dự án sẽ có 2 ứng dụng web chính với design language thống nhất:

### Web Client (User-facing)

- **Mục đích**: Chat interface cho end users tương tác với AI
- **Design inspiration**: x.ai Grok, OpenAI ChatGPT
- **Key features**:
  - Minimalistic và intuitive
  - Dark mode as default với light mode option
  - Real-time chat với typing indicators
  - Message history và conversation management
  - Multi-modal input (text, voice future)

### Web Admin (Admin-facing)

- **Mục đích**: Dashboard quản lý users, analytics, system settings
- **Design inspiration**: Modern admin dashboards với AI-powered insights
- **Key features**:
  - Analytics dashboard với charts/graphs
  - User management với advanced filtering
  - System monitoring và health checks
  - Content moderation tools
  - Configuration management

## I. Design System Foundation

### 1.1 Color Palette

#### Dark Mode (Primary Theme)

**Background Colors:**

- `--bg-primary: #0A0A0A` - Main background - Almost black
- `--bg-secondary: #121212` - Card/Panel background - Dark grey
- `--bg-tertiary: #1A1A1A` - Hover states
- `--bg-elevated: #242424` - Elevated surfaces (modals, dropdowns)

**Text Colors (WCAG Compliant):**

- `--text-primary: #FAFAFA` - Primary text - Off-white (4.5:1 contrast)
- `--text-secondary: #E0E0E0` - Secondary text - Light grey
- `--text-tertiary: #A0A0A0` - Tertiary/disabled text
- `--text-inverse: #1A1A1A` - Text on light backgrounds

**Brand/Accent Colors:**

- `--accent-primary: #3B82F6` - Primary blue - CTAs, links
- `--accent-secondary: #8B5CF6` - Purple - Highlights
- `--accent-success: #10B981` - Green - Success states
- `--accent-warning: #F59E0B` - Amber - Warnings
- `--accent-error: #EF4444` - Red - Errors
- `--accent-info: #06B6D4` - Cyan - Info

**Chat Specific Colors:**

- `--chat-user-bubble: #2563EB` - User message - Deep blue
- `--chat-ai-bubble: #374151` - AI message - Dark grey
- `--chat-user-text: #FFFFFF` - White text on blue
- `--chat-ai-text: #F3F4F6` - Light text on grey
- `--chat-timestamp: #9CA3AF` - Timestamp grey
- `--chat-divider: #1F2937` - Divider between messages

**Border Colors:**

- `--border-primary: #2A2A2A` - Default borders
- `--border-secondary: #3A3A3A` - Hover borders
- `--border-focus: #3B82F6` - Focus state - Blue

#### Light Mode (Secondary Theme)

- `--bg-primary-light: #FFFFFF`
- `--bg-secondary-light: #F9FAFB`
- `--bg-tertiary-light: #F3F4F6`
- `--text-primary-light: #111827`
- `--text-secondary-light: #4B5563`
- `--border-primary-light: #E5E7EB`

### 1.2 Typography

**Font Stack:**

```css
--font-sans:
  -apple-system,
  BlinkMacSystemFont,
  "SF Pro Display",
  "Segoe UI",
  Roboto,
  "Helvetica Neue",
  Arial,
  sans-serif;

--font-mono:
  "SF Mono",
  Consolas,
  "Liberation Mono",
  Menlo,
  monospace;
```

**Type Scale:**

- `--text-6xl: 3.75rem / 1` - 60px - Hero titles
- `--text-5xl: 3rem / 1` - 48px - Page titles
- `--text-4xl: 2.25rem / 1.1` - 36px - Section headers
- `--text-3xl: 1.875rem / 1.2` - 30px - Card headers
- `--text-2xl: 1.5rem / 1.3` - 24px - Large body
- `--text-xl: 1.25rem / 1.4` - 20px - Emphasized text
- `--text-lg: 1.125rem / 1.5` - 18px - Large body
- `--text-base: 1rem / 1.5` - 16px - Default body
- `--text-sm: 0.875rem / 1.5` - 14px - Small text
- `--text-xs: 0.75rem / 1.5` - 12px - Captions

**Font Weights:**

- `--font-light: 300` - Light text
- `--font-normal: 400` - Body text
- `--font-medium: 500` - Emphasized
- `--font-semibold: 600` - Headings
- `--font-bold: 700` - Strong emphasis

### 1.3 Spacing & Layout

**Base Unit: 4px (0.25rem)**

**Spacing Scale:**

- `--space-0: 0` - 0px
- `--space-1: 0.25rem` - 4px
- `--space-2: 0.5rem` - 8px
- `--space-3: 0.75rem` - 12px
- `--space-4: 1rem` - 16px
- `--space-5: 1.25rem` - 20px
- `--space-6: 1.5rem` - 24px
- `--space-8: 2rem` - 32px
- `--space-10: 2.5rem` - 40px
- `--space-12: 3rem` - 48px
- `--space-16: 4rem` - 64px
- `--space-20: 5rem` - 80px

**Container Widths:**

- `--container-sm: 640px` - Small devices
- `--container-md: 768px` - Medium devices
- `--container-lg: 1024px` - Large devices
- `--container-xl: 1280px` - Extra large
- `--container-2xl: 1536px` - 2X large
- `--chat-max-width: 768px` - Max width for chat messages
- `--sidebar-width: 280px` - Conversation history sidebar

**Border Radius:**

- `--radius-sm: 0.25rem` - 4px - Small elements
- `--radius-md: 0.5rem` - 8px - Buttons, inputs
- `--radius-lg: 0.75rem` - 12px - Cards
- `--radius-xl: 1rem` - 16px - Large cards
- `--radius-2xl: 1.5rem` - 24px - Modals
- `--radius-full: 9999px` - Full round - Avatars, pills

**Shadows (Dark Mode Optimized):**

- `--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.5)`
- `--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.5)`
- `--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.6)`
- `--shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.7)`
- `--shadow-glow: 0 0 20px rgba(59, 130, 246, 0.3)` - Blue glow for focus

### 1.4 Grid System

**Responsive Breakpoints:**

- `--screen-sm: 640px` - Mobile landscape
- `--screen-md: 768px` - Tablet
- `--screen-lg: 1024px` - Desktop
- `--screen-xl: 1280px` - Large desktop
- `--screen-2xl: 1536px` - Extra large desktop

**Layout Patterns:**

- Single Column (Mobile): < 768px - Full width content
- Two Column (Tablet): 768px - 1024px - Sidebar + Main
- Three Column (Desktop): > 1024px - Sidebar + Main + Panel

### 1.5 Animation & Transitions

**Timing Functions:**

- `--ease-in: cubic-bezier(0.4, 0, 1, 1)`
- `--ease-out: cubic-bezier(0, 0, 0.2, 1)`
- `--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1)`
- `--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)`

**Duration:**

- `--duration-fast: 150ms` - Hover effects
- `--duration-normal: 250ms` - Default transitions
- `--duration-slow: 350ms` - Complex animations
- `--duration-slower: 500ms` - Page transitions

**Micro-interactions:**

- Button hover: Subtle scale (1.02) + brightness
- Card hover: Lift effect (translateY -2px) + shadow
- Input focus: Glow effect (box-shadow) + border color
- Message send: Slide up + fade in
- Typing indicator: Pulsing dots animation

## II. Component Library

### 2.1 Core Components (Radix UI based)

#### Button Component

**Variants:** primary, secondary, ghost, danger

**Sizes:** xs (28px), sm (32px), md (40px default), lg (48px), xl (56px)

**States:** Default, Hover, Active, Focus, Disabled, Loading

**Implementation:** [apps/web-client/src/components/ui/button.tsx]

#### Input Fields

**Types:** Text Input, Textarea, Select, Multi-select, Date Picker, Search

**States:** Default, Focus (blue border + glow), Error, Success, Disabled

**Implementation:** [apps/web-client/src/components/ui/input.tsx]

#### Card Component

**Variants:** Default, Interactive (hover), Bordered

**Structure:** CardHeader, CardTitle, CardDescription, CardContent, CardFooter

**Implementation:** [apps/web-client/src/components/ui/card.tsx]

#### Modal/Dialog

**Structure:** DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter

**Animation:** Overlay fade in, Content scale + fade

**Implementation:** [apps/web-client/src/components/ui/dialog.tsx]

#### Avatar Component

**Sizes:** xs (24px), sm (32px), md (40px default), lg (48px), xl (64px)

**States:** Image loaded, Fallback (initials), Loading (skeleton), Status indicator

**Implementation:** [apps/web-client/src/components/ui/avatar.tsx]

### 2.2 Chat-Specific Components

#### Message Bubble

**Structure:** User message (right aligned, blue), AI message (left aligned, grey)

**Features:** Message header (author, time), Message text, Message actions on hover

**Animation:** Slide up + fade in

**Implementation:** [apps/web-client/src/components/chat/message-bubble.tsx]

#### Typing Indicator

**Animation:** Pulsing dots with staggered delays

**Implementation:** [apps/web-client/src/components/chat/typing-indicator.tsx]

#### Chat Input

**Features:** Auto-resize textarea, Attach file button, Send button, Keyboard shortcuts (Enter to send, Shift+Enter for new line)

**Implementation:** [apps/web-client/src/components/chat/chat-input.tsx]

#### Conversation Sidebar

**Features:** New Chat button, Search conversations, Conversation list (scrollable), User profile (sticky bottom)

**Implementation:** [apps/web-client/src/components/chat/conversation-sidebar.tsx]

### 2.3 Admin Components

#### Data Table

**Features:** Column sorting, Global search, Column filters, Pagination, Row selection, Bulk actions, Export to CSV/Excel, Column visibility toggle

**Implementation:** [apps/web-admin/src/components/admin/data-table.tsx]

#### Analytics Card

**Variants:** Metric card (single value), Chart card (with graph), Progress card (with progress bar), Comparison card (multiple metrics)

**Implementation:** [apps/web-admin/src/components/admin/analytics-card.tsx]

#### Charts

**Library:** Recharts or Tremor

**Types:** Line Chart, Bar Chart, Pie/Donut Chart, Area Chart, Heatmap

**Implementation:** [apps/web-admin/src/components/admin/charts/]

## III. Web Client - Detailed Screens

### 3.1 Authentication Pages

#### Login Page

**Layout:** Centered card (max-width: 400px), Logo, Email input, Password input (show/hide toggle), Remember me checkbox, Forgot password link, Primary button "Sign in", OAuth buttons (Google), Sign up link

**Validation:** Real-time email format validation, Error messages below inputs, Loading state on button

**Implementation:** [apps/web-client/src/app/(auth)/login/page.tsx]

#### Register Page

**Additional Fields:** Full Name, Confirm Password, Terms & Conditions checkbox, Password strength meter

**Password Strength Levels:** Weak (0-25% red), Fair (26-50% orange), Good (51-75% yellow), Strong (76-100% green)

**Implementation:** [apps/web-client/src/app/(auth)/register/page.tsx]

#### Forgot Password Page

**Flow:** Enter email → Send reset link → Check email → Click link → Enter new password → Confirm → Success → Redirect to login

**Implementation:** [apps/web-client/src/app/(auth)/forgot-password/page.tsx]

### 3.2 Main Chat Interface

**Layout (Desktop):**

- Left Sidebar (280px): New Chat button, Search conversations, Conversation list, User profile
- Main Chat Area (flex-1, max 768px centered): Header, Messages container (scrollable), Typing indicator, Input area (sticky bottom)
- Right Panel (320px, optional, collapsible): Conversation settings, Participants, Shared files, Quick actions

**Message Types:**

1. Text Message - Plain text with markdown support, Code blocks with syntax highlighting, Links with preview cards
2. System Message - Centered, grey text, Used for timestamps, status updates
3. Error Message - Red border, error icon, Retry button
4. Loading Message - Skeleton or typing indicator, Shown while AI is generating

**Message Actions (on hover):** Copy message, Edit (user messages only), Delete (user messages only), Regenerate (AI messages), Like/Dislike (feedback), Share

**Implementation:**

- Layout: [apps/web-client/src/components/chat/chat-layout.tsx]
- Messages: [apps/web-client/src/app/(dashboard)/chat/page.tsx]

### 3.3 User Settings

**Navigation Tabs:** Profile, Preferences, Security, Notifications, Billing (if applicable), API Keys (for developers)

**Profile Tab:** Avatar Upload, Full Name, Email (verified status), Username, Bio, Save Changes button

**Implementation:** [apps/web-client/src/app/(dashboard)/settings/profile/page.tsx]

**Preferences Tab:** Language selection, Theme (Dark/Light/Auto), Chat settings (Auto-scroll, Show timestamps, Message grouping, Font size), Accessibility (High contrast mode, Screen reader optimizations)

**Implementation:** [apps/web-client/src/app/(dashboard)/settings/preferences/page.tsx]

**Security Tab:** Change password, Two-factor authentication (2FA) with QR code, Active sessions (List of devices, Revoke access), Delete account (danger zone)

**Implementation:** [apps/web-client/src/app/(dashboard)/settings/security/page.tsx]

## IV. Web Admin - Detailed Screens

### 4.1 Dashboard (Overview)

**Layout:**

- Header: Dashboard title, User menu, Settings
- Sidebar: Dashboard, Users, Analytics, Messages, Settings, Admin section, Logout
- Main Content:
  - Metrics Row: Total Users, Messages, Active Users, Revenue (with percentage change and sparkline)
  - Charts Row: User Growth Chart (Line Chart), Revenue Chart (Area Chart), Message Activity Heatmap
  - Recent Activity Table: User avatar + name, Action performed, Timestamp (relative), Status badge, Quick actions

**Implementation:** [apps/web-admin/src/app/(dashboard)/dashboard/page.tsx]

### 4.2 User Management

**Features:** User list with search/filter, User details modal, Bulk actions (activate, deactivate, delete), User roles management, Activity logs

**User List Table:** Avatar, Name, Email, Role, Status columns, Search bar, Filter dropdown, Export button, Pagination

**Filters:** Role (Admin, User, Moderator), Status (Active, Inactive, Banned), Date range, Sort by (Name, Email, Date, Activity)

**User Details Modal:** Profile information, Activity timeline, Message history, Edit user button, Deactivate/Delete buttons

**Implementation:**

- Page: [apps/web-admin/src/app/(dashboard)/users/page.tsx]
- Modal: [apps/web-admin/src/components/admin/user-details-modal.tsx]

### 4.3 Analytics

**Tabs:** Overview, Users, Messages, Performance, Custom Reports

**Overview Tab:** Key metrics summary, Trends visualization, Comparison charts (day/week/month/year), Export to PDF/CSV

**Users Tab:** User acquisition funnel, Retention chart, Cohort analysis, Geographic distribution map, Device/browser breakdown

**Messages Tab:** Total messages sent, Average messages per user, Peak activity times, Popular topics/keywords, Sentiment analysis

**Performance Tab:** API response times, Error rates, Uptime statistics, Server resources (CPU, Memory, Disk)

**Implementation:** [apps/web-admin/src/app/(dashboard)/analytics/page.tsx]

### 4.4 System Settings

**Categories:** General, Email, Security, API, Advanced

**General Settings:** Site name, Site logo, Default language, Timezone, Maintenance mode toggle

**Email Settings:** SMTP configuration, Email templates, Test email function

**Security Settings:** Password policy, Session timeout, IP whitelist/blacklist, Rate limiting, CORS settings

**API Settings:** API keys management, Webhooks configuration, Rate limits, Documentation link

**Implementation:** [apps/web-admin/src/app/(dashboard)/settings/page.tsx]

## V. Responsive Design

### 5.1 Breakpoints Strategy

**Mobile First Approach:**

- Mobile (default): < 640px
- Tablet: @media (min-width: 768px)
- Desktop: @media (min-width: 1024px)
- Large Desktop: @media (min-width: 1280px)

### 5.2 Mobile Layout (< 768px)

**Web Client Mobile:**

- Hide sidebar by default (hamburger menu)
- Full-width messages
- Sticky header + input
- Swipe gestures (back, delete)
- Bottom tab navigation (optional)

**Web Admin Mobile:**

- Collapsible sidebar
- Stacked metric cards
- Horizontal scroll for tables
- Simplified charts
- Touch-friendly buttons (min 44px)

### 5.3 Tablet Layout (768px - 1024px)

**Two-column layout:**

- Show sidebar (toggleable)
- Medium-width messages (60%)
- Side-by-side charts (admin)

### 5.4 Touch Interactions

**Touch Targets:** Minimum size: 44x44px (iOS HIG), Spacing between: 8px minimum, Active state feedback (scale down on press)

**Gestures:** Swipe left (Delete), Swipe right (Archive/mark as read), Pull down (Refresh), Long press (Context menu)

## VI. Accessibility (WCAG 2.1 AA)

### 6.1 Color Contrast

**Requirements:**

- Normal text (< 18px): 4.5:1 minimum
- Large text (≥ 18px): 3:1 minimum
- UI components: 3:1 minimum

**Testing Tools:** WebAIM Contrast Checker, Chrome DevTools Accessibility tab, WAVE browser extension

### 6.2 Keyboard Navigation

**Focus Indicators:** 2px solid outline with offset

**Tab Order:** Skip to main content link → Header navigation → Main content → Sidebar → Footer

**Keyboard Shortcuts:**

- `Tab`: Next element
- `Shift + Tab`: Previous element
- `Enter`: Activate button/link
- `Space`: Toggle checkbox/select
- `Escape`: Close modal/dropdown
- `Arrow keys`: Navigate lists/menus

**Custom Shortcuts (Chat):**

- `Ctrl/Cmd + K`: Open search
- `Ctrl/Cmd + N`: New conversation
- `Ctrl/Cmd + /`: Show shortcuts help
- `Alt + ↑/↓`: Navigate conversations

### 6.3 Screen Reader Support

**Semantic HTML:** Use proper HTML5 elements (header, nav, main, aside, footer)

**ARIA Labels:** All interactive elements have descriptive labels, Form validation with aria-invalid and aria-describedby

**Live Regions:** Announcements for new messages with role="status" aria-live="polite"

### 6.4 Visual Accessibility

**Font Size:** Minimum base: 16px, User can zoom up to 200% without breaking layout

**Text Spacing:** Line height: 1.5 minimum, Paragraph spacing: 2x font size

**Focus Management:** Trap focus in modals, Return focus after modal close, Skip to main content link

**Alternative Text:** All images have alt text, Decorative images: alt="", Avatar images: Descriptive alt text

## VII. Performance Optimization

### 7.1 Loading Strategy

**Critical Rendering Path:**

1. Inline critical CSS (above fold)
2. Defer non-critical CSS
3. Async load JavaScript
4. Lazy load images

**Code Splitting:** Route-based splitting, Component-based splitting for heavy components

**Image Optimization:** Next.js Image component (automatic optimization), WebP format with fallback, Responsive images (srcset), Lazy loading, Blur placeholder

### 7.2 Perceived Performance

**Skeleton Screens:** Show content structure while loading

**Optimistic UI:** Show immediate feedback before API response, Update UI immediately on action, Revert if API call fails

**Loading States:** Button loading (spinner inside), Page loading (full-screen or top bar), Partial loading (specific sections)

### 7.3 Caching

**Browser Caching:** Static assets: 1 year, API responses: Vary by endpoint, User data: Session storage

**Service Worker:** Cache static assets, Offline support (basic), Background sync for messages

## VIII. Tech Stack Implementation

### 8.1 Frontend Stack

**Core:**

- Next.js 14+ (App Router)
- TypeScript 5+
- React 18+

**Styling:**

- Tailwind CSS 4
- CSS Variables (theme tokens)
- clsx / cn utility (conditional classes)

**UI Components:**

- Radix UI (unstyled primitives)
- Lucide React (icons)
- Framer Motion (animations)

**State Management:**

- Zustand (global state)
- React Query (server state)
- Context API (theme, auth)

**Forms:**

- React Hook Form
- Zod (validation)

**Charts:**

- Recharts or Tremor

**Utilities:**

- date-fns (date formatting)
- clsx (conditional classes)
- nanoid (unique IDs)

### 8.2 Project Structure

```
apps/web-client/
├── public/
│   ├── fonts/
│   ├── images/
│   └── icons/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (dashboard)/
│   │   │   ├── chat/
│   │   │   └── settings/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/                 # Base components
│   │   │   ├── button.tsx
│   │   │   ├── input.tsx
│   │   │   ├── card.tsx
│   │   │   └── ...
│   │   ├── chat/               # Chat components
│   │   │   ├── message-bubble.tsx
│   │   │   ├── chat-input.tsx
│   │   │   └── typing-indicator.tsx
│   │   ├── layouts/
│   │   │   ├── header.tsx
│   │   │   ├── sidebar.tsx
│   │   │   └── footer.tsx
│   │   └── features/
│   ├── hooks/
│   │   ├── use-chat.ts
│   │   ├── use-auth.ts
│   │   └── use-theme.ts
│   ├── lib/
│   │   ├── api.ts
│   │   ├── utils.ts
│   │   └── constants.ts
│   ├── stores/
│   │   ├── auth-store.ts
│   │   ├── chat-store.ts
│   │   └── theme-store.ts
│   ├── styles/
│   │   ├── globals.css
│   │   └── theme.css
│   └── types/
│       ├── api.ts
│       └── models.ts
├── .env.local
├── next.config.js
├── tailwind.config.js
├── tsconfig.json
└── package.json
```

### 8.3 Component Example

**Button Component Implementation:**

- File: [apps/web-client/src/components/ui/button.tsx]
- Uses: class-variance-authority for variants, Radix UI Slot for composition, cn utility for conditional classes
- Variants: primary, secondary, ghost, danger
- Sizes: xs, sm, md, lg, xl
- States: loading state with spinner, disabled state

## IX. Implementation Phases

### Phase 1: Design System Setup (Week 1)

**Todos:** design-system-1 through design-system-9

- Initialize Tailwind CSS 4 configuration in web-client and web-admin
- Create CSS variables file with theme tokens
- Build base UI components (Button, Input, Card, Dialog, Avatar)
- Setup theme switching system (dark/light mode)
- Initialize Storybook for component documentation

**Parallel Work:**

- Agent 1: Tailwind setup + CSS variables
- Agent 2: Button + Input components
- Agent 3: Card + Dialog + Avatar components
- Agent 4: Theme system + Storybook setup

### Phase 2: Web Client - Authentication (Week 2)

**Todos:** auth-1 through auth-5

- Login page with form validation
- Register page with password strength indicator
- Forgot password flow
- OAuth integration (Google)
- Auth state management with Zustand

**Parallel Work:**

- Agent 1: Login + Register pages
- Agent 2: Forgot password flow
- Agent 3: OAuth integration
- Agent 4: Auth store implementation

### Phase 3: Web Client - Chat Interface (Week 3-4)

**Todos:** chat-1 through chat-8

- Chat layout structure (sidebar + main + optional panel)
- Message bubble components (user + AI)
- Chat input with auto-resize
- Typing indicator with animation
- Conversation sidebar with search
- Message actions menu (copy, edit, delete, regenerate)
- WebSocket integration for real-time messaging
- Chat store with Zustand

**Parallel Work:**

- Agent 1: Chat layout + Message bubbles
- Agent 2: Chat input + Typing indicator
- Agent 3: Conversation sidebar + Message actions
- Agent 4: WebSocket client + Chat store

### Phase 4: Web Client - Settings & Profile (Week 5)

**Todos:** settings-1 through settings-5

- User profile page with avatar upload
- Settings layout with tabs
- Preferences tab (language, theme, chat settings, accessibility)
- Security tab (change password, 2FA with QR code, active sessions)
- API keys management page

**Parallel Work:**

- Agent 1: Profile page + Settings layout
- Agent 2: Preferences tab
- Agent 3: Security tab
- Agent 4: API keys management

### Phase 5: Web Admin - Dashboard (Week 6-7)

**Todos:** admin-1 through admin-6

- Admin dashboard layout with sidebar
- Analytics card component (metric, chart, progress, comparison variants)
- Dashboard overview page with metrics
- User growth chart (Line Chart with Recharts)
- Revenue chart (Area Chart)
- Recent activity table with pagination

**Parallel Work:**

- Agent 1: Dashboard layout + Analytics cards
- Agent 2: User growth chart
- Agent 3: Revenue chart
- Agent 4: Recent activity table

### Phase 6: Web Admin - User Management (Week 8)

**Todos:** admin-7 through admin-10

- User management page with search and filters
- DataTable component (sorting, filtering, pagination, bulk actions)
- User details modal (profile, activity timeline, message history)
- Bulk actions implementation (activate, deactivate, delete)

**Parallel Work:**

- Agent 1: User management page + DataTable
- Agent 2: User details modal
- Agent 3: Bulk actions implementation

### Phase 7: Web Admin - System Settings (Week 9)

**Todos:** admin-11 through admin-14

- System settings page with tabs (General, Email, Security, API, Advanced)
- General settings form (site name, logo, language, timezone, maintenance mode)
- Email settings form (SMTP configuration, email templates, test email)
- Security settings form (password policy, session timeout, IP whitelist/blacklist, rate limiting, CORS)

**Parallel Work:**

- Agent 1: Settings page + General settings
- Agent 2: Email settings
- Agent 3: Security settings

### Phase 8: Responsive & Accessibility (Week 10)

**Todos:** responsive-1 through responsive-4, accessibility-1 through accessibility-4

- Mobile responsive layouts for web-client (hide sidebar, full-width messages, sticky header/input)
- Mobile responsive layouts for web-admin (collapsible sidebar, stacked metrics, horizontal scroll tables)
- Tablet optimizations (two-column layout, medium-width messages)
- Touch-friendly interactions (44px minimum touch targets, swipe gestures)
- Keyboard navigation (focus indicators, tab order, custom shortcuts)
- ARIA labels and semantic HTML
- Screen reader support (live regions, proper labels)
- WCAG 2.1 AA compliance verification

**Parallel Work:**

- Agent 1: Mobile responsive (web-client)
- Agent 2: Mobile responsive (web-admin) + Tablet
- Agent 3: Accessibility (keyboard + ARIA)
- Agent 4: Screen reader + WCAG testing

### Phase 9: Performance & Optimization (Week 11)

**Todos:** performance-1 through performance-5

- Code splitting (route-based and component-based)
- Image optimization (Next.js Image component, WebP format, responsive images, lazy loading)
- Lazy loading (components, images, routes)
- Caching strategy (browser caching, service worker, API response caching)
- Lighthouse optimization (target: Performance 90+, Accessibility 95+, Best Practices 95+, SEO 100)

**Parallel Work:**

- Agent 1: Code splitting + Lazy loading
- Agent 2: Image optimization
- Agent 3: Caching strategy
- Agent 4: Lighthouse optimization

### Phase 10: Testing & Polish (Week 12)

**Todos:** testing-1 through testing-6

- Unit tests for UI components (Jest + React Testing Library)
- Unit tests for hooks and stores
- E2E tests for critical flows (Playwright or Cypress)
- Cross-browser testing (Chrome, Firefox, Safari, Edge)
- Performance testing (Lighthouse, WebPageTest)
- Bug fixes and polish (animations, micro-interactions, edge cases)

**Parallel Work:**

- Agent 1: Component unit tests
- Agent 2: Hooks/stores unit tests
- Agent 3: E2E tests
- Agent 4: Cross-browser + Performance testing
- Agent 5: Bug fixes and polish

## X. Design Resources & References

### 10.1 Inspiration Sources

- x.ai Grok UI - Minimalistic, intuitive chat interface
- OpenAI ChatGPT - Industry-standard AI chat
- Claude.ai - Clean, professional design
- Vercel AI Chat - Modern chat SDK examples
- Linear App - Beautiful dark mode UI

### 10.2 Design Tools

- Figma: UI design and prototyping
- Storybook: Component development and documentation
- Chromatic: Visual regression testing
- Tailwind UI: Premium component examples
- Shadcn UI: High-quality component library

### 10.3 Color Tools

- Coolors: Color palette generation
- Contrast Checker: WCAG compliance
- ColorBox: Dark mode palette creation
- Palettte: Color scheme explorer

### 10.4 Typography Resources

- Fontsource: Self-hosted fonts
- Modern Font Stacks: System font combinations
- Type Scale: Typography scale generator

### 10.5 Icon Libraries

- Lucide React: Modern icon set (recommended)
- Heroicons: Tailwind's icon library
- Phosphor Icons: Flexible icon family
- Feather Icons: Minimalist icons

## XI. Common Patterns & Best Practices

### 11.1 Component Patterns

- Compound Components (Card with CardHeader, CardContent, etc.)
- Render Props (DataTable with custom row rendering)
- Controlled Components (Input with value/onChange)

### 11.2 State Management Patterns

- Zustand Store for global state (auth, chat, theme)
- React Query for server state (API data, caching)
- Context API for theme and auth context

### 11.3 API Integration Pattern

- React Query hooks (useQuery, useMutation)
- Query invalidation on mutations
- Optimistic updates for better UX

### 11.4 Error Handling

- Error Boundary for component error catching
- Toast notifications for user feedback (using sonner or similar)
- Form validation with Zod schemas

## XII. Deployment Considerations

### 12.1 Build Optimization

**Next.js Config:**

- Image optimization with WebP/AVIF formats
- Remove console.log in production
- CSS optimization
- Environment-specific configurations

### 12.2 Environment Variables

- Development: NEXT_PUBLIC_API_URL=http://localhost:5001/api/v1
- Production: NEXT_PUBLIC_API_URL=https://api.goodgo.vn/api/v1
- WebSocket URLs for real-time features

### 12.3 Performance Metrics

**Target Lighthouse Scores:**

- Performance: 90+
- Accessibility: 95+
- Best Practices: 95+
- SEO: 100

**Core Web Vitals:**

- LCP (Largest Contentful Paint): < 2.5s
- FID (First Input Delay): < 100ms
- CLS (Cumulative Layout Shift): < 0.1

## Research Sources

- xAI UI & Management Console
- Grok UI Figma Community
- OpenAI Apps SDK UI
- OpenAI UI Guidelines
- 16 Chat UI Design Patterns
- UI/UX Design Trends 2026
- Modern Web Experience Design

---

**Document Version:** 1.0

**Last Updated:** 2026-01-02

**Status:** Ready for Implementation