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>
2026-05-17 17:51:39 +00:00
parent 5c6d703774
commit 6593bdf689
28 changed files with 904 additions and 247 deletions
@@ -1,8 +1,39 @@
 # Foundations · Spacing

-Reference documentation for the **spacing** foundation. The canonical token values
-live in [`../../design.md`](../../design.md) and the machine-readable export
-in [`../../tokens/`](../../tokens/).
+KDS is built on a **4px base unit**. All spacing, sizing, and layout dimensions are multiples of 4.

-This page is for human-facing rationale: when to use which token, examples,
-and platform notes.
+## Scale
+
+| Token | px | rem | Use |
+|-------|-----|-----|-----|
+| `0`  | 0   | 0     | Reset |
+| `1`  | 4   | 0.25  | Hairline / icon-to-text |
+| `2`  | 8   | 0.5   | Tight stack |
+| `3`  | 12  | 0.75  | Default field-to-label |
+| `4`  | 16  | 1     | Default container padding (mobile) |
+| `5`  | 20  | 1.25  | Card inner gap |
+| `6`  | 24  | 1.5   | Default card padding, section gap |
+| `8`  | 32  | 2     | Form section separator |
+| `10` | 40  | 2.5   | Page section separator (small) |
+| `12` | 48  | 3     | Page section separator (default) |
+| `16` | 64  | 4     | Hero block padding |
+| `20` | 80  | 5     | Marketing hero |
+| `24` | 96  | 6     | Marketing hero, very generous |
+
+## Density
+
+Product apps expose `[data-density="compact|default|cozy"]` on the `<html>` root (see kdcmapper). Each density rebinds two CSS variables:
+
+| Density | `--gap` | `--pad` |
+|---------|---------|---------|
+| compact | 12px (`3`) | 14px |
+| default | 18px | 22px |
+| cozy    | 18px | 22px |
+
+Use density for table-heavy / wizard-heavy screens. Don't fork component padding per screen — change density instead.
+
+## Rules
+
+- ✅ Always pick from the scale. If the value isn't on the scale, you're probably making the wrong choice.
+- ✅ Pair gap and padding from the same step where possible (`gap-4` inside `p-4`).
+- ❌ Don't use 1px, 3px, 5px etc. as spacing — those are border / decoration only.