design-tokens

Design Tokens — emit first, enforce always

Token-first, enforced at generation time, is the single mechanism most correlated with "designed vs slop" output across every premium AI-UI tool (v0 mandates tokens; Lovable scans each generation for violations and auto-corrects; Subframe cascades them). Do the same: emit the signature before the first component, then let nothing use a value that isn't in it.

1. Emit tokens.css before any component

Don't start from a blank page — that's how the median wins. Start from a kit: copy the chosen direction's ready theme from ${CLAUDE_PLUGIN_ROOT}/tools/kits/ (each ships a real, non-default typeface, a committed palette, radius/shadow, and a reduced-motion path — and already passes the linter). Install its fonts (the header line: npm i @fontsource…). Or run /uiforge:reskin <image|url> to derive tokens from a reference. The bare ${CLAUDE_PLUGIN_ROOT}/tools/tokens.template.css is the fallback when no kit fits. Tune the roles to the brand, but keep components consuming var(--…) or the generated utilities (bg-bg, text-fg, bg-primary, bg-surface, text-muted, border-border) — never literals:

:root {
  /* color — semantic ROLES, not raw hex at point of use */
  --bg: …; --fg: …;                 /* base surface + text */
  --surface: …; --on-surface: …;    /* raised card + its text */
  --muted: …; --border: …;          /* secondary text, hairlines */
  --primary: …; --on-primary: …;    /* the ONE accent + its text */
  --ring: …;                        /* focus ring, ≥3:1 */

  /* space — 8px grid (4px half-step); ONE scale */
  --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
  --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px;

  /* radius — one vocabulary */
  --radius-sm: …; --radius: …; --radius-lg: …;

  /* elevation — one light source, monotonic */
  --shadow-1: 0 1px 2px rgb(0 0 0 / .06);
  --shadow-2: 0 2px 6px rgb(0 0 0 / .08);
  --shadow-3: 0 8px 24px rgb(0 0 0 / .12);

  /* type — sizes from ONE ratio; role line-heights */
  --text-xs: …; --text-sm: …; --text-base: 16px; --text-lg: …;
  --text-xl: …; --text-2xl: …; --text-3xl: …; --text-display: …;
  --leading-tight: 1.1; --leading-snug: 1.25; --leading-normal: 1.5;
  --font-display: …; --font-text: …; --font-mono: …;
}