Run: demo-token-cleanup

• branch: claude/demo-token-cleanup-pipeline-wmmccp
• pr: #699

Spec: Demo colour-token cleanup

• slug: demo-token-cleanup
• personas: admin, csm, sdm, expert, vendor, customer
• touches: apps/demo/components/sidebar.tsx, apps/demo/components/dashboard
• complexity: standard

Problem

Demo is the design source of truth, yet it hardcodes raw palette colours in places that CONVENTIONS.md explicitly forbids ("Don't hardcode raw palette colours … use tokens"). The demo sidebar uses bg-blue-600, text-gray-900/600/400, bg-white, border-gray-200 and hover:bg-gray-100 instead of the shared --sidebar-*/semantic tokens, and several demo dashboard components hardcode grays where web uses semantic tokens. Left as-is, "match demo" would propagate raw palette colours into web and block a consistent light/dark result. This is stub 3 of the demo-web-parity epic (initiative: Refine the Bridge / objective Q2 2026 — O1 vendor engagement): per the styling decision, demo is fixed up to the design system so web can reliably match demo's light output and future dark-mode work has a clean base.

Proposed change

Replace demo's hardcoded raw colours with the shared semantic tokens (--sidebar-*, bg-card, text-muted-foreground, text-foreground, border-border, etc.), starting with apps/demo/components/sidebar.tsx and extending to demo dashboard components under apps/demo/components/dashboard/ that hardcode grays. Demo's layout and logic stay unchanged — this is a colour-token pass only. Light-mode output must remain visually unchanged (or improved).

Acceptance criteria

• apps/demo/components/sidebar.tsx uses --sidebar-*/semantic tokens; no bg-blue-600, text-gray-*, bg-white, border-gray-* or hover:bg-gray-* literals remain.
• Demo dashboard components under apps/demo/components/dashboard/ that hardcoded grays now use semantic tokens (text-muted-foreground, text-foreground, border-border, bg-card, etc.).
• Demo light-mode output is visually unchanged (or improved) — layout and logic untouched.
• pnpm lint passes with no new raw-colour violations.

Out of scope

• Adding a theme provider / dark mode to demo (follow-on decision, not this epic).
• Component variant reconciliation (stub 1, design-system-reconciliation).
• Any raw-colour cleanup outside apps/demo (web/dashboards components).

Open questions

• none

Build notes: demo-token-cleanup

• commits: feat: demo-token-cleanup — sidebar uses --sidebar-* tokens, feat: demo-token-cleanup — dashboard components use semantic colour tokens

What changed

• apps/demo/components/sidebar.tsx: every raw palette literal replaced with --sidebar-* / semantic tokens — chrome/borders → bg-sidebar/border-sidebar-border, brand mark & notification badge → bg-sidebar-primary/text-sidebar-primary-foreground, nav hover/active → bg-sidebar-accent/ text-sidebar-foreground, secondary text → text-muted-foreground, mobile scrim → bg-foreground/20.
• apps/demo/components/dashboard/** (66 components): neutral grays mapped to semantic tokens on a consistent scale — gray-900/800/700 → text-foreground, gray-600/500/400/300 → text-muted-foreground, border-gray-* → border-border, bg-white → bg-card, bg-gray-50/100/200 → bg-muted, hovers → hover:bg-muted/hover:text-foreground. The blue accent (bg-blue-500/600, text-blue-*) → bg-primary/text-primary, blue tints → bg-primary/10.
• Dark neutral CTA buttons (bg-gray-900 text-white hover:bg-gray-700) → bg-foreground text-background hover:bg-foreground/90; the urgent action pill's translucent overlay (bg-white/20) → bg-primary-foreground/20, and its white-on-primary text → text-primary-foreground.

Acceptance criteria status

• apps/demo/components/sidebar.tsx uses --sidebar-*/semantic tokens; no bg-blue-600, text-gray-*, bg-white, border-gray-* or hover:bg-gray-* literals remain — verified by grep (0 matches).
• Demo dashboard components under apps/demo/components/dashboard/ that hardcoded grays now use semantic tokens — 66 components converted; 0 in-scope gray/blue/white/black literals remain by grep.
• Demo light-mode output is visually unchanged (or improved) — layout/logic untouched (colour-class swaps only); token light values track the prior grays (foreground=gray-900, muted-foreground=gray-600, border=gray-200, card=white).
• pnpm lint passes with no new raw-colour violations — only colour-class strings changed; verified in CI.

Verify result

• mechanical checks (format · lint · typecheck · build) run in CI + the Vercel preview, not here. Release reads them back from the PR's check runs. No check is expected to fail.

Notes for review

• Scope boundary held deliberately: semantic status colours (emerald/red/amber for RAG, urgency, deltas) were left as-is — they're status indicators, not the grays/blue-accent this cleanup targets, and reconciling them into success/warning/destructive tokens is variant-reconciliation (stub 1), explicitly out of scope here. The 5 remaining text-white literals all sit on those kept status surfaces.
• Neutral shades were collapsed onto the two-tier token scale (foreground/muted-foreground), so a few gray-400 captions render one step darker (gray-600). This is the intended "fix demo up to the design system" result — worth a glance on the demo preview to confirm it reads as improved.
• No theme provider was added to demo (out of scope); light-mode is unchanged. The tokens are now dark-mode-ready for the follow-on epic.

Release: demo-token-cleanup

• pr: https://github.com/sustentus/sustentus/pull/699 · merged: <pending — this run>
• CI: green — Quality Project ✓, Migrate preview database ✓, Project run labels ✓, Vercel previews ✓ (demo + web Ready). Claude review action skipped (ENABLE_CLAUDE_REVIEW off) → diff reviewed inline here.
• technical docs: no technical docs impact — colour-token swap only; no app/route/env var/build/architecture change.
• business docs: no business docs impact — no user-facing product behaviour changed (demo is an internal design-reference app; layout/logic untouched).
• release notes: none — internal design-system refactor; no end-user behaviour change and no investor angle.
• sent: none — no investor update (internal change).

Review summary

• Reviewed the full 71-file diff (67 demo components + run artifacts) at medium effort (complexity: standard).
• Scope verified: 0 in-scope raw palette literals (gray/blue/standalone white/black) remain in the sidebar or dashboard tree; 0 malformed token classes.
• Semantic status colours (emerald/red/amber for RAG, urgency, deltas) preserved verbatim — 17 occurrences removed == 17 added (prettier class-reordering only, no removals). Left as-is deliberately: out of scope (variant reconciliation = stub 1).
• Nuanced pairings handled correctly: dark neutral CTAs → bg-foreground text-background; translucent overlay on the primary action pill → bg-primary-foreground/20 text-primary-foreground; white-on-primary text → text-primary-foreground.
• No cleanup surfaced — mechanical colour-class swaps only, no dead code or scaffolding introduced.

Acceptance check (vs spec)

• apps/demo/components/sidebar.tsx uses --sidebar-*/semantic tokens; no bg-blue-600/text-gray-*/bg-white/border-gray-*/hover:bg-gray-* literals — verified by grep (0 matches).
• Demo dashboard components that hardcoded grays now use semantic tokens — 66 components converted; grep confirms 0 in-scope literals remain.
• Demo light-mode output visually unchanged (or improved) — layout/logic untouched; demo Vercel preview built Ready; token light values track prior grays.
• pnpm lint passes with no new raw-colour violations — Quality Project CI check green.