Conventions

A design system is mostly a list of arguments nobody has to have twice. These are the ones this kit has settled.

Prefer secondary to outline

An outline draws a line around everything it touches. A screen full of them is a grid of boxes with no hierarchy, and those borders start competing with the ones carrying real structure — a card edge, a table rule, a divider. A tint separates without adding another line.

outline stays in the API for the case it is right: a control on an already-tinted surface, where a second fill would compete instead of separate.

Meaning goes in colour, not variant

A badge's variant is a treatment; its color is what it means. Status belongs in the colour.

passedfailedrunningqueued

Controlled and uncontrolled, always both

Every stateful component accepts value and defaultValue. A component that only works controlled forces state upward for no reason.

Verify against the compiled CSS

A Tailwind class that never generates looks exactly like one that was never written. Class names built by template literal are invisible to the scanner and silently produce nothing — which is why the colour sets are written out in full.

This generates no CSS
tsx
// Tailwind scans source text, so it never sees the result.
const set = (name: string) => '[--ui:var(--' + name + ')]'

// Written out, it does:
const colorSet = {
  blue: '[--ui:var(--blue)] [--ui-fg:var(--blue-foreground)]',
}