feat: design system v1.0.0 — reconcile tokens from cross-repo audit

Extracted real production usage from 8 KDC repos and consolidated the
consensus (kdcsurveyadd / kdcvault / kdc_void_planner) into the canonical
design.md + tokens.

Highlights:
- brand.ink #000000 -> #1A1530 (purple-tinted, matches real usage)
- brand.canvas #F5F4F0 -> #F7F4ED (warm)
- neutral ramp rebuilt around ink (purple-tinted, not cold slate)
- semantic palette retuned for warm canvas + soft tints
- elevation shadows retinted with brand-ink rgb
- new accent.gold (product) and accent.mint (marketing) tokens
- real themes/light, themes/dark, themes/high-contrast
- fleshed out every component + foundation README
- docs/consolidation-2026-05.md captures the full audit + drift inventory

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

components/navigation/README.md

@@ -1,25 +1,50 @@
 # Navigation
 
-Specification for the **navigation** primitive.
+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
-TODO — drop `anatomy.svg` next to this file.
+
+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
-- default
-- (list per-component variants)
 
-## States
-default · hover · focus-visible · active/pressed · disabled · loading
+| 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
-See `design.md` → `components.navigation.*`.
+
+`components.button.*` (icon buttons), `colors.surface.*`, `colors.border.*`, `elevation.focusRing`.
 
 ## Accessibility
-- All interactive instances are keyboard-reachable.
-- Focus state has ≥ 3:1 contrast against its background.
-- Pair color with an icon or text to convey meaning.
+
+- 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
-- ✅ Use the canonical token references.
-- ❌ Don't hardcode colors, sizes, or radii.
+
+- ✅ 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.