# SagePHR Dashboard Redesign Spec

## Overview
Replace top horizontal navigation with a collapsible sidebar + persistent top header strip. Full-width layout with respectable padding. Modern, unique, accessible, non-generic design.

## Architecture

### Layout Structure
```
┌─────────────────────────────────────────────────┐
│ Top Header Strip (sticky, slight transparency)  │
├────────┬────────────────────────────────────────┤
│        │                                        │
│ Side   │  Main Content (full-width w/ padding)  │
│ bar    │                                        │
│        │                                        │
├────────┴────────────────────────────────────────┤
│ Mobile: Bottom Tab Bar (5 key items)            │
└─────────────────────────────────────────────────┘
```

### Sidebar
- Left side, collapsible
- Expanded: Icon + label for each nav group
- Collapsed: Icon-only with tooltips
- State: Persisted in localStorage, default expanded on desktop (≥1024px), collapsed on mobile
- Desktop: Always visible (expanded or collapsed)
- Mobile (<768px): Hidden entirely; navigation via bottom tab bar
- Tablet (768-1023px): Collapsed by default, can expand as overlay

### Nav Groups
Clicking a sidebar group item navigates to that group's landing page. Sub-items within a group are displayed as horizontal tabs/menu on the group page itself.

| Group | Icon | Landing Route | Sub-items (horizontal tabs on page) |
|-------|------|---------------|--------------------------------------|
| Dashboard | Home | /dashboard | (single page, no tabs) |
| Analytics | BarChart3 | /analytics | (single page, no tabs) |
| Health | Activity | /vitals | Vitals, Medications, Symptoms, Lab Results, History |
| Care | HeartHandshake | /appointments | Appointments, Care Plans, Care Groups, Emergency |
| Communication | MessageCircle | /messages | Messages, Notifications, Tasks |
| Health AI | Brain | /health-ai/symptom-checker | Symptom Checker, Drug Interactions |

Sidebar Footer (bottom-pinned):
- Profile (User icon)
- Settings (Settings icon)
- Collapse/Expand toggle button

### Top Header Strip
- Sticky at top, z-index above sidebar
- Slight transparency on scroll (backdrop-blur + semi-transparent bg)
- Left: Sage PHR logo/brand mark + sidebar collapse toggle (hamburger on mobile)
- Right: Search bar (expandable), Notifications bell (with badge), User avatar dropdown, Theme toggle (light/dark/system)
- Height: ~56-64px
- Full width (spans across sidebar + content area)

### Main Content Area
- Full width of remaining space (NO max-w-7xl constraint)
- Padding: px-6 lg:px-8 left/right
- Vertical padding: py-6

### Mobile Bottom Tab Bar
- Keep existing MobileNav pattern (5 items max)
- Items: Home, Health, Care, Messages, More (opens remaining)

## Design Requirements

### Color DNA
- Keep existing sage green / warm stone palette
- Keep all CSS custom properties and design tokens
- Sidebar bg: Slightly differentiated from content (e.g., stone-100 light / appropriate dark equivalent)

### Dark/Light Mode
- Use existing CSS custom property system (data-theme="dark")
- All new components use semantic color tokens (no hardcoded colors)
- Theme toggle: light / dark / system preference
- Smooth transition between modes

### Accessibility (CRITICAL)
- All existing a11y modes must work: high-contrast, colorblind, large text, extra-large text, reduced motion
- WCAG 2.1 AAA target
- Min touch targets: 44px
- Skip links still work
- Sidebar keyboard navigable (arrow keys, Enter, Escape)
- Focus management with visible focus rings
- aria-expanded, aria-current="page", proper roles
- Screen reader announcements for sidebar state changes
- All icons: aria-hidden="true" with text labels (or sr-only when collapsed)
- Tab order: skip link → header → sidebar → main content
- Sidebar animations respect prefers-reduced-motion

### Responsiveness
- Desktop (≥1024px): Sidebar expanded, full content width
- Tablet (768-1023px): Sidebar collapsed, overlay when expanded
- Mobile (<768px): No sidebar, bottom tab bar, hamburger opens full-screen nav

## Implementation

### New Shared Components (packages/ui/src/components/ui/)
1. sidebar.tsx — Collapsible sidebar
2. sidebar-item.tsx — Nav item with icon + label + tooltip
3. header-strip.tsx — Top header bar
4. theme-toggle.tsx — Light/dark/system toggle
5. page-tabs.tsx — Horizontal tabs for group sub-navigation
6. search-bar.tsx — Expandable search
7. notification-bell.tsx — Bell with unread badge
8. user-menu.tsx — Avatar dropdown

### App Changes (apps/web/src/)
1. components/layout/AppShell.tsx — Complete rewrite
2. Add PageTabs to group landing pages (vitals, appointments, messages, health-ai)
3. Remove max-w-7xl from main content
4. New hooks: useSidebarState (localStorage), useScrollTransparency

### Group Page Tabs
Each group page gets horizontal tabs for its sub-routes:
- /vitals → tabs: Vitals, Medications, Symptoms, Lab Results, History
- /appointments → tabs: Appointments, Care Plans, Care Groups, Emergency
- /messages → tabs: Messages, Notifications, Tasks
- /health-ai/* → tabs: Symptom Checker, Drug Interactions

### Quality Gates
- pnpm lint passes
- pnpm build passes  
- pnpm test passes
- All routes accessible
- Dark mode verified
- Keyboard navigation works
- No hardcoded colors