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>
This commit is contained in:
Paul Roberts
@@ -0,0 +1,72 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user