portfolio/.ralph/plan.md

Sidebar-First Navigation Refactor Plan

Scope

Refactor dashboard navigation so section jumping is sidebar-driven across desktop and mobile, remove rendered TopBar/SubNav from dashboard flow, and eliminate offset/scroll artifacts caused by legacy top-nav layout assumptions.

Current State Findings

• src/components/DashboardLayout.tsx still renders TopBar + SubNav and offsets the main flex layout by --topbar-height and --subnav-height.
• src/components/Sidebar.tsx has profile/tags/alerts but no section navigation and no mobile collapse/expand behavior.
• src/components/SubNav.tsx contains section jump logic and labels (including disallowed recruiter label mismatch: Significant Interventions).
• src/hooks/useActiveSection.ts maps section IDs to outdated tile keys (core-skills, career-activity, education) that do not reflect current data-tile-id anchors in DashboardLayout.tsx.

Implementation Plan

1) Make DashboardLayout sidebar-first and remove top-nav render path

File: src/components/DashboardLayout.tsx

• Remove imports/usages of TopBar and SubNav from rendered output.
• Remove topbar/subnav animation variants and dead section-click handler tied to SubNav.
• Rework root layout to a single full-height flex shell with no marginTop or calc(100vh - topbar/subnav) offsets.
• Keep main content scroll container behavior and anchor IDs unchanged (data-tile-id values remain jump targets).
• Pass navigation support props to sidebar (active section + section click callback) so jumping logic lives in sidebar.

2) Add recruiter-facing sidebar navigation + mobile rail/drawer behavior

File: src/components/Sidebar.tsx

• Introduce a canonical nav config array with required order/labels and icon mapping:
  • overview / UserRound / tile patient-summary
  • projects / Pill / tile projects
  • experience / Workflow / tile section-experience
  • education / GraduationCap / tile section-education
  • skills / Wrench / tile section-skills
• Add Navigation subsection with buttons/links for the five sections (icon + text in expanded mode).
• Keep a separate My Data subsection above Navigation in expanded mode (profile block remains here).
• Implement mobile-first collapse model:
  • Default mobile state collapsed.
  • Top hamburger control toggles expanded/collapsed.
  • Collapsed mobile rail renders hamburger + five icon-only jump controls.
  • Expanded mobile state renders full sidebar content (My Data, Navigation, tags, alerts/highlights).
• Preserve desktop expanded behavior (full content visible), with nav included.
• Ensure controls are keyboard operable and include ARIA semantics:
  • toggle button: aria-label, aria-expanded, aria-controls
  • nav region: semantic <nav aria-label="Sidebar navigation">
  • current section indicator via aria-current="page" (or equivalent) on active nav item.
• Add visible focus styles for nav/toggle controls (via class or inline style).

3) Move section scroll/jump logic from SubNav into sidebar callbacks

Files: src/components/DashboardLayout.tsx, src/components/Sidebar.tsx

• Implement shared scrollToSection(tileId) callback in layout, passed to sidebar.
• Use smooth scrollIntoView({ behavior: 'smooth', block: 'start' }) to preserve existing behavior.
• Keep compatibility with command palette actions that already target data-tile-id anchors.

4) Fix active-section tracking for sidebar highlighting

File: src/hooks/useActiveSection.ts

• Update sectionTileMap to match current tile IDs:
  • patient-summary -> overview
  • projects -> projects
  • section-experience -> experience
  • section-education -> education
  • section-skills -> skills
• Verify observer root behavior still works with new scroll container; if needed, scope observer root to main scroll area for robust active-state transitions.

5) CSS cleanup for removed top-nav assumptions and mobile sidebar ergonomics

File: src/index.css

• Remove/retire unused --topbar-height and --subnav-height dependencies in layout styles if no longer referenced.
• Add any small utility classes needed for sidebar rail widths, expanded panel widths, and focus-visible outlines.
• Keep scrollbar styling but ensure no hidden top space appears in sidebar when scrolling (layout should no longer rely on inherited top offsets).
• Remove stale subnav-only selectors if no longer used.

6) Handle obsolete components intentionally

Files: src/components/SubNav.tsx, src/components/TopBar.tsx

• Leave components in tree initially if safer for atomic refactor, but ensure they are not rendered.
• Optional cleanup pass can remove dead exports/importers after behavior is stable.

Risks and Mitigations

• Risk: Active section highlighting may flicker if observer root mismatches scroll container.
  • Mitigation: test with long scroll and set observer root to main content container if required.
• Risk: Mobile sidebar overlay/rail can obstruct content interaction.
  • Mitigation: define clear z-index layering and width; ensure collapsed rail is narrow and predictable.
• Risk: Accessibility regressions on icon-only controls.
  • Mitigation: explicit aria-labels, visible focus ring, keyboard toggle and section activation checks.
• Risk: Existing GP metaphor wording leaks into navigation labels.
  • Mitigation: hardcode recruiter-facing nav labels exactly as required.

Verification Checklist (Builder must execute)

• Functional:
  • No TopBar/SubNav rendered in dashboard flow.
  • Sidebar shows My Data then Navigation with labels: Overview, Projects, Experience, Education, Skills.
  • Desktop sidebar jump controls scroll to correct sections.
  • Mobile default is collapsed rail (hamburger + five icons).
  • Mobile expanded view shows My Data + full Navigation + tags + alerts/highlights.
  • Sidebar upward scroll no longer reveals top spacing artifact.
• Accessibility:
  • Toggle and nav controls keyboard operable.
  • Correct ARIA on toggle/nav regions and active item.
  • Focus-visible indicators are apparent for interactive sidebar controls.
• Build quality gates:
  • npm run lint
  • npm run typecheck
  • npm run build

Suggested Execution Order

1. DashboardLayout structural refactor (remove top-nav render and offset math).
2. Sidebar API + nav/mobile UI implementation.
3. Active-section hook mapping corrections.
4. CSS cleanup and focus styles.
5. Verification and quality gates.

Builder Status (2026-02-16)

• DashboardLayout now renders a full-height sidebar-first shell; TopBar and SubNav are no longer rendered.
• Sidebar now owns section navigation with labels: Overview, Projects, Experience, Education, Skills.
• Expanded sidebar includes distinct My Data section above Navigation.
• Mobile sidebar defaults to collapsed rail (hamburger + icon shortcuts) and expands to full content panel.
• Sidebar/main layout no longer depends on topbar/subnav offsets, removing the hidden top spacing artifact source.
• Active section mapping updated for current tile IDs in useActiveSection.
• Accessibility semantics added for toggle and nav controls (aria-label, aria-expanded, aria-controls, aria-current), with visible focus styling.
• Quality gates run:
  • npm run lint (passes with 2 pre-existing warnings in context files)
  • npm run typecheck (pass)
  • npm run build (pass)