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/modals/README.md

@@ -1,25 +1,40 @@
 # Modals
 
-Specification for the **modals** primitive.
+Overlaid surfaces that interrupt the user — dialogs, confirmations, sheets, drawers. Built on `base-ui` / Radix primitives in the product family (`kdcvault/frontend/src/components/ui/dialog.tsx`, `sheet.tsx`).
 
 ## Anatomy
-TODO — drop `anatomy.svg` next to this file.
+
+See `anatomy.svg`. Backdrop · panel · header (title + close) · body · footer (actions, right-aligned).
 
 ## Variants
-- default
-- (list per-component variants)
 
-## States
-default · hover · focus-visible · active/pressed · disabled · loading
+| Token | Use | Width | Position |
+|-------|-----|-------|----------|
+| `modal.default` | Confirmations, forms (≤ 5 fields) | 480px | centered |
+| `modal.wide` | Multi-step wizards, content browsers | 720px | centered |
+| `modal.sheet` | Slide-in side panel (editing, filters) | 420px | right edge |
+| `modal.drawer` | Bottom sheet (mobile) | 100% | bottom edge |
+| `modal.fullscreen` | Immersive flows | 100% | full viewport |
 
-## Tokens used
-See `design.md` → `components.modals.*`.
+## Tokens & layout
+
+- Radius `rounded.xl` (16px); sheet variants use `rounded.lg` on inner edge only.
+- Background `surface.background`; backdrop `rgba(26,21,48,0.45)`.
+- Shadow `elevation.4` (`0 24px 80px -24px rgba(26,21,48,0.22)`).
+- Padding 24px; footer separated by `1px border.default` top edge.
+- Open animation: `kdc-fade-up` (360ms cubic-bezier, `translateY(6px)` → 0).
 
 ## 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.
+
+- `role="dialog"` (or `alertdialog` for destructive confirmations) with `aria-labelledby` / `aria-describedby`.
+- Trap focus inside the modal; first focusable element receives focus on open.
+- Close on `Esc`; restore focus to the trigger element on close.
+- Backdrop click closes only non-destructive modals; confirmations require explicit action.
+- Disable body scroll while open.
 
 ## Do / Don't
-- ✅ Use the canonical token references.
-- ❌ Don't hardcode colors, sizes, or radii.
+
+- ✅ Right-align primary action in the footer (`primary` or `accent`); secondary / cancel on the left.
+- ✅ Use a `sheet` for editing context that benefits from staying tethered to a list.
+- ❌ Don't stack modals — open a `sheet` from inside a modal instead.
+- ❌ Don't put more than one CTA in a single modal footer.