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.