tailwind-design-system

Tailwind v4 uses CSS-first configuration with @theme blocks instead of tailwind.config.ts. Define tokens like --color-primary and --radius-md inside @theme in your CSS file, and replace @tailwind directives with a single @import "tailwindcss" statement.

Use @custom-variant dark (&:where(.dark, .dark *)) to enable class-based dark mode, then override your CSS variables inside a .dark selector. A ThemeProvider component can toggle the class on the root element with localStorage persistence and prefers-color-scheme detection.

Key changes include replacing tailwind.config.ts with @theme blocks, @tailwind directives with @import "tailwindcss", darkMode config with @custom-variant, and tailwindcss-animate with native CSS keyframes. React 19 also removes the need for forwardRef since ref is passed as a regular prop.

Yes, Tailwind v4 introduces the @utility directive for defining reusable custom utilities directly in CSS. You can compose existing utilities with @apply inside @utility blocks, replacing many use cases that previously required custom plugins.

OKLCH provides better perceptual uniformity than HSL, meaning equal numeric changes produce visually consistent color shifts across hues. Define OKLCH values directly in @theme tokens, and use color-mix() in oklab to generate semi-transparent variants.

Use class-variance-authority (CVA) to define base styles plus variant and size options as a typed configuration object. Combine it with a cn() utility built on clsx and tailwind-merge to merge classes safely without conflicts.