KDCDesignSystem/docs/consolidation-2026-05.md

# Design system consolidation — 2026-05-17

Output of the cross-repo audit that produced **v1.0.0**. Read this first if you're wondering "why does this token look the way it does."

## Scope

Scanned 8 repos under `/root/`:

`kdcsurveyadd` · `kdcvault` · `kdc_void_planner` · `k-d-c-workspace` · `kdcdiary` · `kdctracker` · `kdcdocs` · `kdcmapper`

For each: every distinct colour, font, radius, shadow, and reusable component was extracted via a parallel `Explore` agent. Findings are summarised below; the raw notes are in agent transcripts under `.claude/jobs/`.

## Three families, one canonical

| Family | Repos | Primary | Ink | Canvas | Font | Stack |
|--------|-------|---------|-----|--------|------|-------|
| **Refined product** *(canonical)* | `kdcsurveyadd`, `kdcvault`, `kdc_void_planner` | `#6B35A7` | `#1A1530` | `#F7F4ED` (warm) | Manrope | Tailwind v4 + shadcn/ui + base-ui |
| **Marketing dashboard** | `k-d-c-workspace` (dashboard) | `#6B35A7` | `#1a1530` | `#f7f6fb` (cool) | Manrope | Tailwind v4 + custom components |
| **Legacy / exploratory** *(drift)* | `kdcdiary`, `kdctracker`, `kdcdocs`, `kdcmapper` | varies | varies | varies | Geist or Inter+Outfit | varies |

The product family agrees almost line-for-line on tokens — including the bespoke gold accent `#C9892B`, the focus ring `0 0 0 3px rgba(107,53,167,0.18)`, the ink-tinted shadow stack, and a 4-step radius scale (`4 / 8 / 12 / 16`). v1.0.0 promotes that consensus into the canonical spec.

The dashboard agrees on brand fundamentals (purple, Manrope, ink) but uses a **cooler canvas** (`#f7f6fb`) and a **mint accent** (`#46C194`) instead of gold. Both are now first-class tokens: `brand.canvasCool` and `accent.mint`. Marketing surfaces use those; product surfaces use the warm canvas + gold.

## Drift inventory

| Repo | Primary used | Font used | Status |
|------|--------------|-----------|--------|
| `kdcdiary` | `#6B4EFF` | Geist + JetBrains Mono | drift — different purple, different typeface |
| `kdctracker` | `#6B4EFF` | Geist + JetBrains Mono | drift — same as diary, looks like a shared template |
| `kdcdocs` | `#A37CD9` | Geist + Geist Mono | drift — dark-themed Astro site, lifted purple |
| `kdcmapper` | `#5567E8` (indigo) | Inter + Outfit + JetBrains Mono | drift — indigo palette, no Manrope, glassmorphism style |

**Not in scope for v1.0.0.** A follow-up project should migrate these to canonical — order of cheapest first:

1. **kdctracker** — single-file HTML, ~1 day to swap CSS vars.
2. **kdcdiary** — React app with inline styles, ~2 days.
3. **kdcdocs** — needs a deliberate "light vs dark canonical" decision before migration. Either we adopt a dark theme as canonical for marketing/docs, or we re-skin it onto the light product theme.
4. **kdcmapper** — biggest lift, fully bespoke Tailwind theme. Plan a dedicated re-skin sprint.

## What changed in v1.0.0

See `CHANGELOG.md` for the full diff. Highlights:

- Brand ink moved from pure `#000000` to `#1A1530` — every product surface already uses the purple-tinted ink, the spec was wrong.
- Canvas warmed to `#F7F4ED`.
- Neutral ramp rebuilt around the purple ink so muted text and borders stay on-brand.
- Semantic palette retuned for the warm canvas (`success` `#2F7A5A`, etc.) and each ships a `*Soft` background tint.
- Shadow stack retinted with brand-ink rgb.
- Added `accent.gold` and `accent.mint` as first-class tokens.
- Filled in every previously-stub README in `components/` and `foundations/` with real specs.
- Real `themes/light`, `themes/dark`, `themes/high-contrast` JSON.

## What's still TODO

Carrying these forward to v1.1 (not blockers):

- **Wordmark second-line** — design.md still encodes the secondary lockup at `fontWeight: 200`. The workspace brand guide lists Manrope weights starting at 300; either re-confirm 200 is licensed or bump to 300.
- **Opificio cuts** — only Bold is in `brand/logos-source/`. If Rounded or Regular are licensed, add them with the same naming convention.
- **Workspace brand guide** — `@Context/Assets/Brand/colour-palette.md` still has empty `_Name_` cells. The values in this design system can populate them; do it once and then point the brand guide at this repo as canonical.
- **Component anatomy SVGs** — every component README references `anatomy.svg`. The files exist but are placeholder geometry; commission real ones.
- **Token build pipeline** — `scripts/build-tokens.js` still produces a tokens dump only. A v1.1 should emit Tailwind v4 `@theme` blocks, CSS variables, and Style Dictionary JSON so apps can consume directly.
- **Migration runbooks** — one per drift app (`migrate-kdcdiary.md` etc.), with a token-mapping table so the work is grab-and-go.

## How to use the new spec

1. **In a new Tailwind v4 app**, copy the `@theme` block from `kdcvault/frontend/src/index.css` lines 5–62 — that's the canonical reference implementation.
2. **Import** `@fontsource-variable/manrope` and reference `var(--font-manrope)`.
3. **Always use role tokens** (`text.default`, `surface.canvas`) in component code, never raw palette values.
4. **For a new shadcn component**, `npx shadcn@latest add <component>` then re-style with the existing `.kdc-*` utility classes from `kdcsurveyadd/app/globals.css`.

Questions / drift you spot: open an issue or PR against this repo.