Tailwind design system

How to build a design system on Tailwind CSS v4 that many teams and many apps can use for years: one place to change a value, themes that swap at runtime, components that carry their own accessibility, and machines that stop drift. Checked against Tailwind 4.3.3. If inspect.mjs shows a newer version, check its changelog before relying on version-specific notes here.

The system is the tokens and the rules, not the components. Components are the easy part to copy. What makes a system hold at scale is a closed set of semantic tokens, and lint and CI that make going around them harder than using them.

Measure, never assume. Contrast is computed, classes are compiled, versions are read from the repo. Sources and check dates: SOURCES.md.

Procedure

1. Run node scripts/inspect.mjs from the repo root. It prints the installed Tailwind and related versions, every CSS entry with its @source lines, @theme blocks, dark variant and token counts, surfaces without a foreground token, and v3 leftovers. Work from that, not from memory.
2. Find the task in the table below and read that resource.
3. New system: copy templates/theme.css, then change values, not structure.
4. Make the change.
5. Verify, and report each result:
   • The app or Storybook builds.
   • node scripts/check-contrast.mjs <theme files> passes, after any token change.
   • The Tailwind lint config passes, or node scripts/audit-classes.mjs <dirs> shows counts did not rise.

tokens (DTCG JSON, optional)
   │ generate
   ▼
theme.css ── primitives    :root            --palette-*       never classes
          ── semantic      :root, dark,     --primary         swapped per theme
                           brand blocks
          ── utility map   @theme inline    --color-primary   the public classes
          ── scales        @theme           --text-sm         closed with --*: initial
          ── @source "./components"         the package says where its classes live
   │ @import "@acme/ui/theme.css"
   ▼
app.css  @import "tailwindcss";  one Tailwind build per app
   │
   ▼
lint + audit budgets + contrast + visual and a11y tests in CI

Where to read

Defaults, unless the repo has already decided

Traps

Review checklist

• inspect.mjs output is in the PR or the report, with the Tailwind version
• Primitives are not in @theme. Semantic colours go through @theme inline.
• --color-* is closed, and other scales the system owns are closed
• Every surface token has a -foreground partner, and check-contrast.mjs passes in every mode and brand
• No raw palette classes, arbitrary values, dark: colour overrides or !important in app code, enforced by lint
• Components use semantic classes only, take variants as typed props, and merge className last through the system's cn
• Custom theme keys are registered with the merge config
• The UI package's theme declares its @source, and exports serves theme.css with the style condition
• System CSS is in a layer, with :where() selectors
• Focus is visible at 3:1, targets are at least 24px, reduced motion is respected, in the components themselves
• Breaking changes ship with a major, a changeset, and a codemod or autofix rule
• Deprecated tokens are aliases with a removal version and a lint warning

Related skills

Accessibility criteria in full: wcag-accessibility. Types for component props and variant maps: typescript-safety. Writing the docs pages: plain-docs. Button and error text: ux-copy.