# Navigation

App shell, sidebar, top bar, tabs, breadcrumbs. Reference: `kdcvault/frontend/src/components/ui/sidebar.tsx`, `kdcsurveyadd/components/sidebar-nav.tsx`, `k-d-c-workspace/dashboard/components/AppShell.tsx`.

## Anatomy

App shell = top bar (60px, `surface.background`, hairline bottom border) + sidebar (240px collapsed → 72px icon-only, dark `brand.ink` on workspace; canvas-toned in product apps) + main outlet.

## Variants

| Pattern | Use |
|---------|-----|
| **Top bar + sidebar** | Default product layout (vault, void planner, surveyadd) |
| **Top bar only** | Simple tools (mapper, tracker) |
| **Sidebar collapsible** | `SidebarProvider` controls expanded / icon-only / off-canvas (mobile) |
| **Command palette** | ⌘K trigger; `modal.default` shell over backdrop |
| **Tabs** | In-page section switching — underline (`border.bottom-2 brand.primary` active) |
| **Breadcrumbs** | Hierarchical path; `text.muted` non-active, `text.default` current, `›` separator in `text.disabled` |

## Sidebar items

- 40px row height, 12px horizontal padding, 12px gap between icon and label.
- Icon 20×20px from the curated Phosphor set (see `assets/icons/`).
- Active state: `brand.primarySoft` background, `brand.primary` text, 2px left border in `brand.primary`.
- Hover: `surface.subtle` background.
- Section labels: `caption` uppercase, `text.muted`, 24px row.

## Top bar

- 60px tall, sticky.
- Left: brand mark · workspace switcher. Right: search · notifications · user menu.
- `backdrop-filter: saturate(180%) blur(14px)` on scroll (translucent over content).

## Tokens used

`components.button.*` (icon buttons), `colors.surface.*`, `colors.border.*`, `elevation.focusRing`.

## Accessibility

- Sidebar uses `<nav aria-label="primary">`; in-page tabs use `role="tablist"` / `role="tab"` / `role="tabpanel"`.
- Current page link: `aria-current="page"`.
- Skip-to-content link as the first focusable element, visible on focus.
- Command palette: trap focus, restore on close, announce via `aria-live`.

## Do / Don't

- ✅ Always show the active route — left border + tinted background, not colour-shift alone.
- ✅ Collapse to icon-only below 1024px, off-canvas below 768px.
- ❌ Don't nest more than two sidebar levels — flatten into separate sections.
- ❌ Don't put primary actions in the sidebar — they belong in the top bar or page header.