Tailwind v4 Design System

When to use this

• You are configuring Tailwind v4 and need the CSS-first @theme approach instead of the old JS config.
• You need to define custom design tokens as CSS custom properties that Tailwind consumes natively.
• You want component-level patterns (cva, tailwind-variants) on top of utility classes.
• You are using container queries, cascade layers, or @utility directives in v4.
• Do NOT use this when you need raw DTCG token files or Style Dictionary pipelines; use design-tokens-dtcg instead.

Mental model

Tailwind v4 moves configuration from tailwind.config.js into CSS. The @theme directive defines design tokens as CSS custom properties that Tailwind automatically generates utilities for. Write --color-brand: #3b82f6 inside @theme and you get bg-brand, text-brand, border-brand without any plugin code.

The cascade layers model in v4 is: @layer theme, base, components, utilities. This means utility classes always win over component classes, which always win over base styles, regardless of source order. This is what makes Tailwind composable: you can safely apply both component and utility classes without specificity fights.

@utility lets you register a custom utility with Tailwind's variant system. Write @utility text-balance { text-wrap: balance; } and you can use hover:text-balance, md:text-balance, etc. This replaces the old addUtilities() plugin API.

Container queries are first-class: @container variants like @sm:, @md: etc. respond to a parent container's width instead of the viewport. Combined with @theme tokens, this is how you build truly component-scoped responsive design.