stack/DASHBOARD-REDESIGN-SPEC.md

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