Resolution: This audit led to a full framework migration from Vue 3 to React 19 + shadcn/ui + Zustand. See UX Research & Framework Decision for the evaluation and rationale. Infrastructure cleanup completed in #794. Page implementations tracked as #777--#793.

Context

The web dashboard is functional but has severe UX problems across every page. The setup wizard is the only well-designed flow -- every other tab suffers from static data presentation, missing interactivity, no visual hierarchy, and lack of polish. This planning issue captures the full scope of what needs to change.

Current State Assessment (pre-migration, Vue era)

What worked well

• Setup wizard: Clear progress indicators, step validation, back-navigation, completion summary
• ECharts integration: Budget charts render correctly
• DataTables: Sortable, functional tables for approvals/meetings
• Edit mode pattern: GUI vs JSON/YAML toggle on Settings and Company pages
• Error boundaries: Consistent retry UX throughout
• Empty states: Helpful messages with action buttons

What needed fixing (every page)

Dashboard

• Static metric cards with just numbers and icons -- no trends, sparklines, or period comparisons
• No activity feed or recent events timeline
• SpendingSummary chart is too basic -- no budget remaining indicator or forecast
• Layout is sparse -- wastes screen real estate

Task Board

• Kanban cards show only title + priority badge -- no description preview, due dates, or assignee avatars
• No filtering beyond status columns
• No dependency visualization between tasks
• Missing burndown chart, cycle time metrics, velocity tracking
• Task detail panel in sidebar instead of inline editing

Budget Panel

• Only hourly/daily aggregation -- no budget remaining gauge or utilization meter
• No pie/donut chart for cost breakdown by agent, team, or provider
• No threshold alerts or forecast projections
• Agent spending table lacks % of budget column

Approvals

• Dense table hard to scan at a glance
• No grouping by risk level or type
• No urgency indicators ("expires in 3 hours" vs. just timestamp)
• Missing timeline visualization of approval flow

Org Chart

• Only shows structure -- no status indicators on nodes (active/idle/error)
• No team/department stats overlaid (headcount, utilization)
• No auto-layout (manually positioned nodes)
• No pan/zoom state persistence

Agent Profiles

• Cards are info-only -- no status history, performance metrics, or utilization data
• No filtering by department/level/status
• Agent detail page is minimal -- just a 2-column grid of static fields
• No activity timeline or task history per agent

Company

• Minimal visual feedback on save/load states
• No drag-drop reordering
• Agent/Department cards inconsistent with other pages showing the same data

Providers

• No status indicators for provider health (up/down/degraded)
• No usage/call metrics per provider
• No routing logic visualization
• Cards don't show available models

Settings

• No search across settings
• Floating "Save All Dirty" button easy to miss
• No setting dependency indicators

Messages

• Very basic -- no sender indicators, timestamp grouping, or threading
• No channel badges or unread counts

Meetings

• No timeline visualization
• Token usage shown as text, not progress bar
• Contributions displayed as plain text, not formatted dialogue

Artifacts

• Placeholder only ("Coming Soon")

Cross-cutting problems

1. Static data everywhere: Cards/tables just display data with no hover tooltips, transitions, or visual feedback
2. No real-time indicators: WebSocket exists but UI updates are silent -- no "just updated" visual cues
3. No loading skeletons: Only on initial page load, not on card-level refreshes
4. Inconsistent components: Agent cards look different on every page they appear
5. No keyboard navigation: Beyond basic form inputs
6. Missing animations: No page transitions, card entrance effects, or data change animations

Related issues (v0.5)

• feat: interactive org chart with department/team CRUD and detail pages #674: Absorbed into feat: Org Chart page (living nodes, status, CRUD, department health) #778 (Org Chart page)
• feat: implement company builder interactive wizard (UI + API) #238: Absorbed into feat: Setup Wizard rebuild in React (template comparison, cost estimator) #783 (Setup Wizard rebuild)
• feat: implement visual workflow editor #247: Visual workflow editor (v0.5.9)
• feat: sink configuration UI in web dashboard settings page #565: Sink configuration UI in settings (v0.5.2)
• feat: embed MkDocs build output in React web dashboard at /docs #295: Embed docs in dashboard (v0.5.4)
• feat: template comparison view and cost estimator in setup wizard #726: Absorbed into feat: Setup Wizard rebuild in React (template comparison, cost estimator) #783 (Setup Wizard rebuild)

Available leverage from tooling upgrades

• Vite 8: Rolldown (10-30x faster builds), console forwarding, built-in devtools
• Vitest 4: Tags, aroundEach/aroundAll hooks, mockThrow, coverage.changed
• Recharts 3: Composable chart components for React
• @xyflow/react 12: Interactive node-based diagrams (org chart, workflow editor)
• Framer Motion 12: Spring-based animations, layout transitions, gesture interactions

Scope

This is a planning issue. The work has been broken into focused sub-issues:

1. Design system (feat: design tokens and core UI components #775): Consistent component library, shared patterns, loading states, animations
2. Dashboard overhaul (feat: Dashboard page (metric cards, sparklines, activity feed, budget burn) #777): Sparklines, activity feed, budget gauge, real-time indicators
3. Per-page rebuilds (feat: Org Chart page (living nodes, status, CRUD, department health) #778--feat: Login page + first-run bootstrap (login, setup, agent activation) #789): Each page rebuilt with React + shadcn/ui
4. Real-time UX (feat: real-time UX and WebSocket-driven animations #790): WebSocket-driven live updates with visual feedback
5. Responsive (feat: responsive implementation across all pages #791): Mobile and tablet breakpoints
6. Accessibility (feat: accessibility audit and keyboard navigation #792): Keyboard navigation, WCAG compliance
7. Performance QA (feat: performance optimization and visual QA baselines #793): Lighthouse baselines, visual regression
8. Cleanup (chore: remove Vue codebase and update infrastructure #794): Remove Vue remnants, update infrastructure

Acceptance criteria

• Audit all existing UX-related issues and ensure coverage
• Create focused sub-issues for each workstream
• Design system principles documented
• Priority order established based on user impact