design-system

Build a systematic design system

The brand skill decides the identity; the frontend-design skill decides how a surface looks. This pack decides how that look is structured so it scales: a three-layer token architecture with one source of truth, component specs that cover every state, and checks that stop raw values leaking back in. Load a reference when you need depth:

The architecture in one breath

/* PRIMITIVE — raw values, no meaning. Change rarely. */
--blue-600: oklch(55% 0.2 264);
/* SEMANTIC — purpose. The theme seam: light/dark/brand override only this layer. */
--color-primary: var(--blue-600);
/* COMPONENT — per-component knobs, referencing semantic tokens. */
--button-bg: var(--color-primary);

Components consume component or semantic tokens — never a primitive, never a literal. Themes (dark, high contrast, a second brand) re-point semantic tokens and nothing else.

Source of truth. If the repo keeps tokens as W3C Design Tokens Community Group (DTCG) JSON — the format reached its first stable version, 2025.10, in October 2025 — those files are the source: tokens carry $value and $type, aliases are written {color.blue.600}, and a build tool (Style Dictionary or the repo's equivalent) generates CSS variables, Tailwind theme and native values. Edit the JSON and regenerate; never hand-edit generated output. If the repo has only CSS custom properties, those are the source. Do not introduce a second source.

Steps

1. Read what exists. search_lore for design-system ADRs; find token files (*.tokens.json, tokens/, theme.ts, :root blocks, Tailwind config), the build command that generates outputs, and two sibling components. Extend the existing system in its idiom; never add a competing one.
2. Audit before adding. Count literals in component styles (commands below). Every leak you touch is either replaced by an existing token or justifies a new one.
3. Place each new token in its layer. Primitive only for a genuinely new raw value; semantic for a new purpose (--color-surface-raised, --space-section); component only when one component must diverge. Names describe purpose, not appearance (--color-danger, not --color-red). Colour primitives in oklch (house idiom), type in a clamp() fluid scale, spacing on one base unit (4px or 8px).
4. Theme at the semantic seam. Dark mode and other themes override semantic tokens in one block ([data-theme="dark"], .dark or @media (prefers-color-scheme: dark), per the repo) and set color-scheme so native controls and scrollbars follow. A theme that overrides a primitive or a component token means the seam is in the wrong place.
5. Verify contrast per theme. For every foreground/background semantic pair actually used (text on surface, text on primary, border on surface, focus ring on surface), compute the WCAG contrast ratio in each theme: 4.5:1 for body text, 3:1 for large text, UI boundaries and focus indicators. oklch lightness is not the WCAG ratio — compute it (a script, the repo's checker, or a test). Record the table.
6. Specify components fully. Variants, sizes (explicit height, padding, font token), and the state matrix — default, hover, focus-visible, active, disabled, loading, error, plus selected/checked where relevant — with the ARIA each state exposes. Priority when several apply: disabled > loading > error > active > focus > hover > default. Focus is always visible (:focus-visible ring from --color-ring, never outline: none alone). Details: the references.
7. Recommending a system for a new product: reason from the product, not a kit — (a) pattern and density (marketing, data-dense dashboard, transactional flow), (b) direction (defer to brand), (c) palette posture (semantic roles incl. success/ warning/danger/info; dark mode only if users need it), (d) accessibility and performance targets stated up front. Output a short rationale plus the token and component scaffold; hand visual execution to frontend-design.
8. Verify and evidence. Regenerate token outputs if the repo builds them and confirm the diff is only what you intended; run lint, type-check and tests; run the leak checks; render the changed components in every theme through the repo's component or screenshot tests where they exist. Record per-AC evidence with the record-evidence skill (leak count before/after, contrast table), then stop.