portfolio/tasks/prd-responsive-scaling.md

# PRD: Responsive Scaling & Mobile Layout

## Introduction

The dashboard is built for 1080p screens. On larger displays (1440p, 4K), everything appears too small — text, spacing, and UI elements don't scale with the viewport. On mobile, the sidebar is completely inaccessible (hidden with no toggle), text doesn't wrap properly and spills off-screen, and several components are unusable at narrow widths.

This PRD addresses viewport-responsive scaling for larger screens and usability fixes for mobile, scoped to the dashboard phase only (TopBar, Sidebar, Card Grid, and all tiles).

## Goals

- Scale the dashboard proportionally on larger viewports (1440p should feel ~25% larger than 1080p)
- Make the sidebar accessible on mobile via a slide-out drawer with toggle
- Ensure all text wraps properly and nothing overflows horizontally at any viewport size
- Maintain the current 1080p experience as the baseline — no changes at that resolution
- Preserve the existing visual design language (fonts, colors, spacing ratios)

## User Stories

### US-000: Skip Boot/Login for Dev Iteration
**Description:** As a developer, I want to skip the boot/ECG/login animation during this feature branch so I can iterate on the dashboard quickly.

**Acceptance Criteria:**
- [ ] In `App.tsx`, initial Phase state changed from `'boot'` to `'pmr'`
- [ ] Boot, ECG, and login code remains — only initial state changes
- [ ] App loads directly to dashboard on refresh
- [ ] Typecheck passes
- [ ] **Reverted in final story (US-013)**

### US-001: Fluid Root Font-Size Scaling
**Description:** As a user on a high-resolution display, I want the dashboard to scale proportionally so that text and UI elements are comfortably sized without manual browser zoom.

**Acceptance Criteria:**
- [ ] `html` element uses a `clamp()`-based font-size that scales with viewport width
- [ ] At 1920px viewport width (1080p), effective font-size remains ~15px (current baseline)
- [ ] At 2560px viewport width (1440p), effective font-size is ~18–19px (~25% increase)
- [ ] At 3840px viewport width (4K), font-size caps at a sensible maximum (~22px)
- [ ] Below 1920px, font-size does not shrink below 15px (mobile/tablet keeps baseline)
- [ ] Typecheck passes

### US-002: Convert Fixed px to rem in Layout Structure
**Description:** As a developer, I need layout measurements to use `rem` so they scale with the root font-size, rather than remaining fixed at px values.

**Acceptance Criteria:**
- [ ] CSS custom properties `--topbar-height`, `--sidebar-width`, `--subnav-height` converted from px to rem
- [ ] `DashboardLayout.tsx` margin/padding/height calculations use rem-based values
- [ ] Card padding converted to rem
- [ ] Grid gaps converted to rem
- [ ] Dashboard content area scales proportionally with root font-size
- [ ] At 1080p, layout looks identical to current (no visual regression)
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-003: Convert Fixed px to rem in Typography
**Description:** As a user on any screen size, I want text to scale with the viewport so it's always readable without zooming.

**Acceptance Criteria:**
- [ ] All inline `fontSize` styles in tile components converted from px to rem (e.g., `13px` → `0.8125rem` based on 16px root, or equivalent relative to 15px base)
- [ ] TopBar text sizes converted to rem
- [ ] Sidebar text sizes converted to rem
- [ ] Card header text sizes converted to rem
- [ ] At 1080p, text sizes are visually identical to current
- [ ] At 1440p, text is proportionally larger and readable
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-004: Convert Fixed px to rem in Spacing & Components
**Description:** As a developer, I need padding, margins, icon sizes, and component dimensions to scale with viewport so the UI stays proportional.

**Acceptance Criteria:**
- [ ] Inline padding/margin values in tiles converted from px to rem
- [ ] Badge/tag padding and sizing converted to rem
- [ ] Icon sizes (where set inline) use rem
- [ ] Border-radius values may remain in px (they don't need to scale)
- [ ] At 1080p, spacing is visually identical to current
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-005: Mobile Sidebar Drawer
**Description:** As a mobile user, I want to access the sidebar content (person details, tags, alerts) via a slide-out drawer so I can see this information without it permanently taking screen space.

**Acceptance Criteria:**
- [ ] TopBar shows a menu/hamburger icon on screens below `lg` breakpoint (1024px)
- [ ] Tapping the icon opens the sidebar as a slide-out drawer overlay from the left
- [ ] Drawer includes a semi-transparent backdrop that closes the drawer on tap
- [ ] Drawer contains the full sidebar content (PersonHeader, Tags, Alerts)
- [ ] Drawer can be closed via the backdrop tap, a close button, or pressing Escape
- [ ] Drawer uses the same animation timing as existing UI (200ms ease-out)
- [ ] Drawer respects `prefers-reduced-motion` (skip to final state)
- [ ] Sidebar remains inline (non-drawer) on `lg+` screens — no behavior change on desktop
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-006: Fix Text Wrapping & Overflow
**Description:** As a mobile user, I want all text content to wrap properly within its containers so nothing is cut off or requires horizontal scrolling.

**Acceptance Criteria:**
- [ ] No horizontal scrollbar appears at any viewport width (320px to 3840px)
- [ ] All text in tile components wraps within its container — no off-screen overflow
- [ ] Long skill names in CoreSkillsTile truncate with ellipsis rather than breaking layout
- [ ] Career Activity entries wrap cleanly at narrow widths
- [ ] PatientSummaryTile stats grid reflows to fewer columns on narrow screens
- [ ] KPI cards in LatestResultsTile stack or reflow on mobile (no horizontal overflow)
- [ ] Education entries wrap properly
- [ ] Project entries wrap properly
- [ ] `overflow-x: hidden` on the main content area as a safety net (not a primary fix — actual wrapping must work)
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-007: Career Constellation Chart — Responsive Container Sizing
**Description:** As a user on any device, I want the D3 career constellation chart (`CareerConstellation.tsx`) to fit its container without overflowing, so the visualization is usable at all viewport widths.

**Acceptance Criteria:**
- [ ] Chart SVG width/height derived from container dimensions (not hardcoded px)
- [ ] Chart re-renders or resizes on viewport/container resize (via `ResizeObserver` or equivalent)
- [ ] D3 force simulation parameters (charge strength, link distance, node spacing) adapt to available width
- [ ] On mobile (<768px), chart remains visible and nodes don't overlap excessively or overflow
- [ ] Node labels remain legible at small sizes (consider hiding secondary labels on narrow viewports)
- [ ] Chart does not cause horizontal scrollbar at any viewport width
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-008: Career Constellation Chart — Mobile Interaction
**Description:** As a mobile user, I want to interact with the career constellation chart using touch so I can explore roles and skills.

**Acceptance Criteria:**
- [ ] Nodes are tappable on touch devices (adequate touch target size, minimum ~44px)
- [ ] Tap on a role node triggers the same action as click (opens role detail)
- [ ] Tap on a skill node triggers the same action as click (opens skill detail)
- [ ] No hover-dependent information is inaccessible on touch (tooltips show on tap or info is always visible)
- [ ] Chart doesn't conflict with page scroll (vertical scroll still works when touching the chart area)
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-009: TopBar Mobile Refinements
**Description:** As a mobile user, I want the TopBar to remain functional and readable at narrow viewport widths.

**Acceptance Criteria:**
- [ ] Hamburger/menu icon appears at the left of the TopBar below `lg` breakpoint
- [ ] Brand text collapses gracefully (already mostly handled — verify no regression)
- [ ] Search trigger remains accessible on mobile (either inline icon or within command palette trigger)
- [ ] Session info collapses gracefully at narrow widths (already mostly handled — verify no regression)
- [ ] TopBar height scales with rem (from US-002)
- [ ] No horizontal overflow from TopBar content
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-010: Verify at Key Viewport Sizes
**Description:** As a developer, I need to verify the dashboard renders correctly at representative viewport sizes to confirm no regressions.

**Acceptance Criteria:**
- [ ] 375px wide (iPhone SE) — single column, drawer sidebar, all text wraps, no overflow
- [ ] 768px wide (iPad portrait) — single column, drawer sidebar, comfortable spacing
- [ ] 1024px wide (iPad landscape / small laptop) — sidebar inline, 2-column grid
- [ ] 1920px wide (1080p) — visually identical to current production
- [ ] 2560px wide (1440p) — ~25% scaled up, proportional layout, readable
- [ ] Typecheck passes
- [ ] Verify in browser using dev-browser skill

### US-011: Re-enable Boot/Login Sequence
**Description:** As a user, I want the full boot → ECG → login experience restored for production.

**Acceptance Criteria:**
- [ ] In `App.tsx`, initial Phase state reverted from `'pmr'` back to `'boot'`
- [ ] Full boot → ECG → login → dashboard sequence works end to end
- [ ] No other changes to `App.tsx`
- [ ] Typecheck passes
- [ ] Verify full sequence works via Playwright MCP

## Functional Requirements

- FR-1: Set `html { font-size: clamp(...) }` that scales from 15px at 1920px to ~22px at 3840px, floored at 15px below 1920px
- FR-2: Convert all CSS custom properties used for layout dimensions (`--topbar-height`, `--sidebar-width`, `--subnav-height`) to rem units
- FR-3: Convert all inline `fontSize`, `padding`, `margin`, and `gap` values in dashboard components from px to rem
- FR-4: Add a mobile sidebar drawer component (slide-from-left overlay, backdrop, close on escape/backdrop-tap)
- FR-5: Add a hamburger menu button to TopBar, visible below `lg` breakpoint, that toggles the sidebar drawer
- FR-6: Apply `overflow-wrap: break-word` and appropriate `min-width: 0` on flex/grid children to prevent text overflow
- FR-7: Ensure `overflow-x: hidden` on the main scrollable content area as a catch-all
- FR-8: Tile content must reflow (fewer grid columns, stacked layout) at narrow viewports rather than overflowing
- FR-9: Career Constellation D3 chart must size to its container, re-render on resize, and adapt force simulation parameters for narrow viewports
- FR-10: D3 chart nodes must have adequate touch targets (44px minimum) and not block page scroll on touch devices

## Non-Goals

- No permanent changes to Boot, ECG, or Login phases (temporarily skipped for dev, restored in final story)
- No changes to the 1080p visual appearance (it's the baseline)
- No changes to color palette, fonts, or design language
- No new responsive breakpoints beyond what Tailwind already provides (xs/sm/md/lg/xl)
- No container queries or component-level responsive logic — viewport scaling via root font-size is the mechanism
- No changes to Command Palette responsive behavior (separate concern)
- No touch gesture support (swipe to open sidebar, etc.)

## Design Considerations

- The sidebar drawer on mobile should visually match the existing sidebar styling — same background (`#F7FAFA`), same border, same content
- The drawer should overlay content with a semi-transparent backdrop, similar to the existing detail panel pattern used for project/career detail expansion
- The hamburger icon should use `lucide-react` (e.g., `Menu` icon) consistent with existing icon usage
- Font-size scaling should be smooth (fluid), not stepped at breakpoints, to avoid jarring jumps during window resize

## Technical Considerations

- **rem base calculation**: Since the current design uses `15px` as the body font-size, the rem conversion should be based on `15px = 1rem` (set on `html`). At 1080p, `1rem = 15px`. At 1440p, `1rem ≈ 18.75px`.
- **Conversion formula**: `px / 15 = rem` (e.g., `13px = 0.867rem`, `48px = 3.2rem`, `272px = 18.133rem`)
- **Tailwind classes**: Tailwind's spacing scale uses a 16px rem base by default. Since we're changing the html font-size, Tailwind rem-based classes (`p-4`, `text-sm`, etc.) will automatically scale. Only inline `px` styles need manual conversion.
- **CSS custom properties**: Convert `--topbar-height: 48px` → `--topbar-height: 3.2rem`, etc.
- **Sidebar drawer state**: Managed via React state in `DashboardLayout.tsx`, passed down or via context. Keep it simple — `useState<boolean>` for open/closed.
- **Animations**: Drawer slide uses `transform: translateX(-100%)` → `translateX(0)` with 200ms ease-out, consistent with existing motion patterns.

## Success Metrics

- At 1440p, the dashboard is comfortably readable without browser zoom adjustments
- On mobile (375px), all content is accessible, readable, and no horizontal scrolling occurs
- Sidebar content is accessible on all screen sizes
- No visual regression at 1080p
- Zero horizontal overflow at any viewport width between 320px and 3840px

## Open Questions

- Should the mobile drawer have a swipe-to-close gesture? (Deferred as non-goal for now, can add later)
- Should the search bar be accessible on mobile via a dedicated icon in TopBar? (Currently hidden below md — may want a small search icon)
- At what viewport width should font scaling cap? (PRD suggests 3840px / ~22px — may need tuning)