Paul Roberts
b635fd1fdb
kdcdocs was sunset earlier — SOPs already merged into kdcsurveyadd /docs. Move it from the migration backlog to an "Archived" row in the consolidation report. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
74 lines
5.2 KiB
Markdown
74 lines
5.2 KiB
Markdown
# 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`, `kdcmapper` | varies | varies | varies | Geist or Inter+Outfit | varies |
|
||
| **Archived** *(out of scope)* | `kdcdocs` | `#A37CD9` | dark | dark | Geist | Sunset — SOPs merged into `kdcsurveyadd /docs`. Read-only reference. |
|
||
|
||
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 |
|
||
| `kdcmapper` | `#5567E8` (indigo) | Inter + Outfit + JetBrains Mono | drift — indigo palette, no Manrope, glassmorphism style |
|
||
|
||
`kdcdocs` was previously sunset (SOPs merged into `kdcsurveyadd /docs`) — excluded from migration.
|
||
|
||
**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. **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.
|