biggus-dickus/docs/superpowers/specs/2026-06-07-design-token-adoption-design.md

Design-Token Adoption Across Feature Screens — Design

Date: 2026-06-07 Status: Approved (brainstorming) — ready for implementation planning. Issue: #49.

Context

web/src/index.css defines a full semantic OKLCH token set (the shadcn defaults: --foreground, --muted-foreground, --primary, --destructive, --accent, --border, --radius, light + .dark) and ui/* components use it. But the feature screens bypass it: ~120 hardcoded Tailwind color utilities outside components/ui/ — text-red-600 ×27 (not --destructive, a different red), text-neutral-400/500/600 ×47 (three shades for "muted text"), bg-neutral-50/100, plus two competing accents (bg-indigo-50/text-indigo-600/ bg-indigo-600 for selection/links/chips vs the near-black --primary for buttons and bg-neutral-800 for the publish stepper). Status colors (visibility badge amber/green, search highlight yellow) aren't tokens; rounded (0.25rem, ×23) ignores the --radius token; ui/Card has zero usages; the uppercase caption label appears with 4 different recipes. (Recent table/detail/toast work did introduce token usage — bg-primary ×6, bg-destructive, text-foreground — so the codebase is now mixed; this finishes the job.)

Decisions (from brainstorming)

1. One brand accent: indigo --primary. Set --primary/--ring to an indigo so primary buttons, selected rows, links, and chips share one recognizable accent (the existing indigo usages map straight onto bg-primary/text-primary).
2. Add status tokens (--success/--warning/--highlight) and route the visibility badge + search highlight through them (via Badge variants).
3. Enforce with a CI/lint guard banning raw color utilities outside components/ui/.
4. Dark-mode toggle stays #59. This migration makes the .dark token set work (semantic tokens adapt), unblocking #59; the toggle/persistence is not in scope.
5. One milestone (the guard can only pass once the migration is complete, so it lands last).

Token changes (web/src/index.css)

• Indigo primary in :root: --primary: oklch(0.511 0.262 276.966) (≈ indigo-600), --primary-foreground: oklch(0.985 0 0), --ring: oklch(0.511 0.262 276.966). In .dark: a lighter indigo that reads on dark (≈ indigo-400, oklch(0.673 0.182 276.966)) + --primary-foreground: oklch(0.205 0 0), matching --ring. (Implementer may fine-tune to a Tailwind indigo shade; keep --primary-foreground contrast AA.)
• Status tokens in :root and .dark, exposed in @theme inline as --color-success, --color-success-foreground, --color-warning, --color-warning-foreground, --color-highlight, --color-highlight-foreground. Light values ≈ success oklch(0.6 0.13 160) / warning oklch(0.72 0.15 75) / highlight oklch(0.905 0.16 100) with readable foregrounds; dark variants adjusted for contrast. --destructive unchanged.
• --accent/--muted stay the neutral shadcn grays (hover/subtle surfaces). Selected/active states use bg-primary/10 (a light indigo tint) rather than repurposing --accent.

Component updates

• ui/badge.tsx: add success and warning variants (token-based, with dark variants); VisibilityBadge (web/src/objects/visibility-badge.tsx) selects a variant — public → success, internal → warning, draft → the default/secondary — instead of patching bg-amber-100/bg-green-100.
• search/highlight.tsx: bg-yellow-200 → bg-highlight (token).
• Shared caption: add a single .label-caption utility (in index.css @layer components, or a tiny ui helper) = text-xs font-medium uppercase tracking-wide text-muted-foreground; replace the 4 ad-hoc recipes (object-detail, object-form, publish-control, field-list, vocabulary-terms).
• ui/Card: adopt for clearly hand-rolled bordered panels where it's a clean swap (e.g. the object-detail container). Not forced onto every bordered div — low priority within scope.

Migration map (mechanical, ~120 sites, outside components/ui/)

From	To
text-red-600	text-destructive
text-neutral-400 / -500 / -600	text-muted-foreground
text-neutral-700 / -900	text-foreground
bg-neutral-50 / -100	bg-muted
bg-neutral-200 (active nav)	bg-accent
bg-indigo-50 (selected row)	bg-primary/10
bg-indigo-600 / text-indigo-600	bg-primary / text-primary
bg-neutral-800 (publish stepper / tabs)	bg-primary (with text-primary-foreground)
bare rounded (×23)	rounded-md
bg-amber-*/bg-green-*/bg-yellow-* (badge/highlight)	via Badge variants / --highlight
Apply judgment on a few one-offs (e.g. border-red-300/border-green-300 on the combobox/drawer
→ border-destructive/border-success or keep neutral border). The goal: **zero raw color
utilities outside components/ui/** after the migration.

Enforcement (web/scripts/check-no-raw-colors.mjs)

A grep-style Node script (mirroring check-bundle-size.mjs) that scans src/**/*.{ts,tsx}, excluding src/components/ui/, and fails (exit 1) if it finds a raw palette utility matching (text|bg|border|ring|fill|stroke|from|to|via)-(neutral|gray|slate|zinc|stone|red|orange|amber| yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}. Print each offending file:line. Add a check:colors script and wire it into the test gate (e.g. the check flow / CI). A short inline allowlist (path or eslint-disable-style comment) only if a genuine exception arises. Added last, after the migration, so the gate is green.

Data flow / architecture

Pure styling refactor — no behavior, routing, API, or data changes. Tokens in index.css → Tailwind utility classes (bg-primary, text-muted-foreground, …) in feature components → resolved at build. ui/* components already consume tokens and gain the new Badge variants.

Error handling / edges

• The migration must not change layout/spacing — only color/radius utilities (and Badge variant selection). Don't restructure markup.
• bg-primary/10 opacity modifier on a token works in Tailwind v4 — verify it resolves.
• A few utilities are genuinely semantic-ambiguous (e.g. text-neutral-900 for an emphasized value vs body) — map to text-foreground; muted captions → text-muted-foreground.
• The enforcement regex must not flag token utilities (text-foreground, bg-primary) or non-color numerics (gap-2, w-44) — scope it to the palette names above.

Testing

• Existing CssCheck story (visibility-badge.stories.tsx) asserts the public badge's resolved bg-green-100 oklch — it must be updated to the new --success token's resolved value (run the story to read the actual computed color, as the original did). Add Badge success/warning stories.
• pnpm typecheck / lint / test / build green; the new check:colors passes (proves the migration is complete — zero raw utilities outside ui/); check:size ≈ unchanged (CSS token churn only); no codename; en/sv untouched (no strings).
• Manual smoke: the app still renders (now indigo-accented); selected rows/links/buttons share the indigo; visibility badges + search highlight use the status tokens; nothing relies on a removed color. (No automated visual-regression in the repo — the guard + updated stories + smoke are the safety net.)

Acceptance criteria

1. --primary/--ring are indigo; primary buttons, selected rows, links, chips use it (one accent). Status tokens (--success/--warning/--highlight) exist (+ @theme + .dark).
2. VisibilityBadge and the search highlight use token-based Badge variants / --highlight (no hardcoded amber/green/yellow); one shared caption utility.
3. No raw color utilities outside components/ui/; bare rounded standardized to the radius token; check:colors guard added to the gate and passing.
4. No behavior/layout change; CssCheck story updated; typecheck/lint/test/build/ check:size green; no codename.
5. Dark-mode tokens are coherent (light + .dark) so #59 (toggle) is unblocked — but the toggle is not added here.

Out of scope → follow-ups

• The dark-mode toggle + persistence (#59) — this only makes the tokens dark-ready.
• Per-screen layout/spacing redesign, density changes, typography scale (#57).
• Forcing ui/Card onto every panel (adopt only the clean swaps).