Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.

Tailwind Design System (v4) Build production ready design systems with Tailwind CSS v4, including CSS first configuration, design tokens, component variants, responsive patterns, and accessibility. Note : This skill targets Tailwind CSS v4 (2024+). For v3 projects, refer to the [upgrade guide](https://tailwindcss.com/docs/upgrade guide). When to Use This Skill Creating a component library with Tailwind v4 Implementing design tokens and theming with CSS first configuration Building responsive and accessible components Standardizing UI patterns across a codebase Migrating from Tailwind v3 to v4 Setting up dark mode with native CSS features Key v4 Changes v3 Pattern v4 Pattern tailwind.config.ts @theme in CSS @tailwind base/components/utilities @import "tailwindcss" darkMode: "class" @custom variant dark (&:where(.dark, .dark )) theme.extend.colors @theme { color : value } require("tailwindcss animate") CSS @keyframes in @theme + @starting style for entry animations Quick Start Core Concepts 1. Design Token Hierarchy 2. Component Architecture Patterns Pattern 1: CVA (Class Variance Authority) Components Pattern 2: Compound Components (React 19) Pattern 3: Form Components Pattern 4: Responsive Grid System Pattern 5: Native CSS Animations (v4) Pattern 6: Dark Mode with CSS (v4) Utility Functions Advanced v4 Patterns Custom Utilities with @utility Define reusable custom utilities: Theme Modifiers Namespace Overrides Semi transparent Color Variants Container Queries v3 to v4 Migration Checklist [ ] Replace tailwind.config.ts with CSS @theme block [ ] Change @tailwind base/components/utilities to @import "tailwindcss" [ ] Move color definitions to @theme { color : value } [ ] Replace darkMode: "class" with @custom variant dark [ ] Move @keyframes inside @theme blocks (ensures keyframes output with theme) [ ] Replace require("tailwindcss animate") with native CSS animations [ ] Update h 10 w 10 to size 10 (new utility) [ ] Remove forwardRef (React 19 passes ref as prop) [ ] Consider OKLCH colors for better color perception [ ] Replace custom plugins with @utility directives Best Practices Do's Use @theme blocks CSS first configuration is v4's core pattern Use OKLCH colors Better perceptual uniformity than HSL Compose with CVA Type safe variants Use semantic tokens bg primary not bg blue 500 Use size New shorthand for w h Add accessibility ARIA attributes, focus states Don'ts Don't use tailwind.config.ts Use CSS @theme instead Don't use @tailwind directives Use @import "tailwindcss" Don't use forwardRef React 19 passes ref as prop Don't use arbitrary values Extend @theme instead Don't hardcode colors Use semantic tokens Don't forget dark mode Test both themes

tailwind-design-system