design-systems

Design System Mechanics

Token structure, shadcn/ui usage, Tailwind v4 features, and component composition — not aesthetic direction.

For palettes, font pairings, category tone, layout direction, and the slop checklist, load the anti-slop-design skill (and its reference.md for full pages / responsive matrices). For general coding workflow, use core Code Discipline.

Inspect the project first: package.json, tailwind.config.*, globals.css, components.json, existing fonts and icon library. Extend what exists; do not replace the design system unprompted.

---

Token Shape (semantic, not hex soup)

Prefer semantic names mapped to CSS variables so themes and shadcn primitives stay aligned:

/* globals.css — Tailwind v4 @theme or :root */
@theme {
  --color-background: …;
  --color-foreground: …;
  --color-primary: …;
  --color-muted: …;
  --color-border: …;
  --radius-md: 8px;
  --font-body: …;
  --font-display: …;
}

• Derive real values from the project brand or anti-slop-design Category Guide — placeholders above are structural only.
• Prefer OKLCH for new token values (oklch(0.65 0.15 250)) — perceptually uniform lightness makes scales and dark-mode variants predictable. Tint neutrals toward the brand hue (chroma 0.005–0.01); never ship pure-gray scales or pure #000/#FFF.
• Three token tiers when the system grows: primitive (--blue-600) → semantic (--color-primary) → component (--button-bg). Components consume semantic tokens; only semantic tokens reference primitives. Skip the component tier until a component actually needs an override.
• Do not default to generic blue/indigo scales or Inter / Roboto unless the project already uses them.
• Status colors: --destructive, --success, etc. — keep consistent with shadcn semantic tokens when present.

---

Typography Mechanics

• Fluid display sizes with clamp(): font-size: clamp(2rem, 1.2rem + 3.5vw, 4rem) — no breakpoint jumps on headings.
• Pair line-height inversely with size: body 1.6–1.8, headings 1.1–1.2. A 56px heading at line-height: 1.6 is broken.
• Tighten tracking as display size grows (letter-spacing: -0.01em to -0.04em above ~32px); never negative-track body text.
• Body measure: max-width: 65ch on prose containers, not pixel guesses.
• Keep ≥1.25 ratio between adjacent type-scale steps; expose the scale as tokens, not ad-hoc text-[17px] values.
• Load fonts with font-display: swap and preconnect; subset when the toolchain supports it.