design-system-guardrails

Design System Guardrails

Every application UI has exactly two sources of truth:

1. The theme (design tokens) — every color, spacing, radius, font, and shadow is defined once.
2. The component library (workshopped in Storybook) — every component is defined and styled once, with all its variants and states.

Application screens only compose. They never define appearance.

Why this matters: when tokens and components live in one place, a rebrand is a one-file change, a component fix propagates everywhere, and there is never a third slightly-different implementation of the same button. Every hardcoded hex value or call-site restyle silently creates a second source of truth that someone else (human or agent) will later copy. These rules exist to make drift impossible, not to slow you down.

---

The five rules

Rule 1 — Tokens are the only styling values

All styling values come from the theme as semantic tokens (named by role: primary, surface, destructive), never as raw values and never as primitive names (blue-500). Semantic names survive rebrands and make dark mode a token swap instead of a rewrite.

• Never hardcode: hex (#3b82f6), rgb()/hsl()/oklch() literals, magic pixel values, or Tailwind arbitrary values (w-[347px], text-[#ff0000], bg-[rgb(0,0,0)]).
• If the value you need doesn't exist, add a token to the theme first, then use it. Never inline it "just this once" — that's how every drifted codebase started.

// ❌ Three new sources of truth
<div className="bg-[#1a56db] p-[13px] rounded-[5px]">
// ✅ Tokens only
<div className="bg-primary p-3 rounded-md">

/* ❌ */ .card { background: #ffffff; border-radius: 8px; }
/* ✅ */ .card { background: var(--color-surface); border-radius: var(--radius-md); }

Rule 2 — Components are defined once, in the library

Every reusable component lives in the component library (e.g. src/components/ui/ or the design-system package) — never inside a screen, page, or feature folder. Every library component has stories covering every variant and interactive state (default, hover, focus, disabled, loading, error, empty).