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

@@ -1,25 +1,37 @@
 # Cards
 
-Specification for the **cards** primitive.
+A surface for grouping related content. Two canonical variants: `default` (flat, hairline border) and `elevated` (lifted shadow).
 
 ## Anatomy
-TODO — drop `anatomy.svg` next to this file.
+
+See `anatomy.svg`. Standard parts: `CardHeader` · `CardTitle` · `CardDescription` · `CardAction` (top-right slot) · `CardContent` · `CardFooter`. Reference: `kdcvault/frontend/src/components/ui/card.tsx`.
 
 ## Variants
-- default
-- (list per-component variants)
+
+| Token | Background | Border | Shadow | Radius | Padding |
+|-------|------------|--------|--------|--------|---------|
+| `card.default` | `surface.background` | `border.default` (1px) | `elevation.1` | `rounded.lg` (12px) | 24px |
+| `card.elevated` | `surface.background` | none | `elevation.3` | `rounded.xl` (16px) | 28px |
+| `card.muted` | `surface.subtle` | `border.subtle` | none | `rounded.lg` | 24px |
+| `card.outlined` | `surface.background` | `border.strong` (1px) | none | `rounded.lg` | 24px |
 
 ## States
-default · hover · focus-visible · active/pressed · disabled · loading
+
+- **Hover (interactive cards only)** — bump shadow one level (`1` → `2`) and shift `translateY(-2px)` over `motion.duration.fast`.
+- **Focus-visible** — apply `elevation.focusRing` on the card root.
+- **Selected** — 2px `brand.primary` left border or full `border.strong` ring.
 
 ## Tokens used
-See `design.md` → `components.cards.*`.
+
+`components.card.*`, `elevation.1`–`3`, `colors.surface.*`, `colors.border.*`.
 
 ## 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.
+
+- If the card is clickable, the entire card is the hit target; expose it as a `<button>` or `<a>` (not a `<div onClick>`).
+- Don't rely on hover state alone to indicate interactivity — pair with cursor + raised elevation.
 
 ## Do / Don't
-- ✅ Use the canonical token references.
-- ❌ Don't hardcode colors, sizes, or radii.
+
+- ✅ Use `card.default` for list rows and grid tiles. Reserve `card.elevated` for modals, popovers, and feature highlights.
+- ❌ Don't nest cards more than one level deep — collapse to sections instead.
+- ❌ Don't mix `card.default` and `card.elevated` in the same grid.