1---
2name: tailwind-design-system
3description: 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.
4---
5 
6# Tailwind Design System (v4)
7 
8Build production-ready design systems with Tailwind CSS v4, including CSS-first configuration, design tokens, component variants, responsive patterns, and accessibility.
9 
10> **Note**: This skill targets Tailwind CSS v4 (2024+). For v3 projects, refer to the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).
11 
12## When to Use This Skill
13 
14- Creating a component library with Tailwind v4
15- Implementing design tokens and theming with CSS-first configuration
16- Building responsive and accessible components
17- Standardizing UI patterns across a codebase
18- Migrating from Tailwind v3 to v4
19- Setting up dark mode with native CSS features
20 
21## Key v4 Changes
22 
23| v3 Pattern                            | v4 Pattern                                                            |
24| ------------------------------------- | --------------------------------------------------------------------- |
25| `tailwind.config.ts`                  | `@theme` in CSS                                                       |
26| `@tailwind base/components/utilities` | `@import "tailwindcss"`                                               |
27| `darkMode: "class"`                   | `@custom-variant dark (&:where(.dark, .dark *))`                      |
28| `theme.extend.colors`                 | `@theme { --color-*: value }`                                         |
29| `require("tailwindcss-animate")`      | CSS `@keyframes` in `@theme` + `@starting-style` for entry animations |
30 
31## Quick Start
32 
33```css
34/* app.css - Tailwind v4 CSS-first configuration */
35@import "tailwindcss";
36 
37/* Define your theme with @theme */
38@theme {
39  /* Semantic color tokens using OKLCH for better color perception */
40  --color-background: oklch(100% 0 0);
41  --color-foreground: oklch(14.5% 0.025 264);
42 
43  --color-primary: oklch(14.5% 0.025 264);
44  --color-primary-foreground: oklch(98% 0.01 264);
45 
46  --color-secondary: oklch(96% 0.01 264);
47  --color-secondary-foreground: oklch(14.5% 0.025 264);
48 
49  --color-muted: oklch(96% 0.01 264);
50  --color-muted-foreground: oklch(46% 0.02 264);
51 
52  --color-accent: oklch(96% 0.01 264);
53  --color-accent-foreground: oklch(14.5% 0.025 264);
54 
55  --color-destructive: oklch(53% 0.22 27);
56  --color-destructive-foreground: oklch(98% 0.01 264);
57 
58  --color-border: oklch(91% 0.01 264);
59  --color-ring: oklch(14.5% 0.025 264);
60 
61  --color-card: oklch(100% 0 0);
62  --color-card-foreground: oklch(14.5% 0.025 264);
63 
64  /* Ring offset for focus states */
65  --color-ring-offset: oklch(100% 0 0);
66 
67  /* Radius tokens */
68  --radius-sm: 0.25rem;
69  --radius-md: 0.375rem;
70  --radius-lg: 0.5rem;
71  --radius-xl: 0.75rem;
72 
73  /* Animation tokens - keyframes inside @theme are output when referenced by --animate-* variables */
74  --animate-fade-in: fade-in 0.2s ease-out;
75  --animate-fade-out: fade-out 0.2s ease-in;
76  --animate-slide-in: slide-in 0.3s ease-out;
77  --animate-slide-out: slide-out 0.3s ease-in;
78 
79  @keyframes fade-in {
80    from {
81      opacity: 0;
82    }
83    to {
84      opacity: 1;
85    }
86  }
87 
88  @keyframes fade-out {
89    from {
90      opacity: 1;
91    }
92    to {
93      opacity: 0;
94    }
95  }
96 
97  @keyframes slide-in {
98    from {
99      transform: translateY(-0.5rem);
100      opacity: 0;
101    }
102    to {
103      transform: translateY(0);
104      opacity: 1;
105    }
106  }
107 
108  @keyframes slide-out {
109    from {
110      transform: translateY(0);
111      opacity: 1;
112    }
113    to {
114      transform: translateY(-0.5rem);
115      opacity: 0;
116    }
117  }
118}
119 
120/* Dark mode variant - use @custom-variant for class-based dark mode */
121@custom-variant dark (&:where(.dark, .dark *));
122 
123/* Dark mode theme overrides */
124.dark {
125  --color-background: oklch(14.5% 0.025 264);
126  --color-foreground: oklch(98% 0.01 264);
127 
128  --color-primary: oklch(98% 0.01 264);
129  --color-primary-foreground: oklch(14.5% 0.025 264);
130 
131  --color-secondary: oklch(22% 0.02 264);
132  --color-secondary-foreground: oklch(98% 0.01 264);
133 
134  --color-muted: oklch(22% 0.02 264);
135  --color-muted-foreground: oklch(65% 0.02 264);
136 
137  --color-accent: oklch(22% 0.02 264);
138  --color-accent-foreground: oklch(98% 0.01 264);
139 
140  --color-destructive: oklch(42% 0.15 27);
141  --color-destructive-foreground: oklch(98% 0.01 264);
142 
143  --color-border: oklch(22% 0.02 264);
144  --color-ring: oklch(83% 0.02 264);
145 
146  --color-card: oklch(14.5% 0.025 264);
147  --color-card-foreground: oklch(98% 0.01 264);
148 
149  --color-ring-offset: oklch(14.5% 0.025 264);
150}
151 
152/* Base styles */
153@layer base {
154  * {
155    @apply border-border;
156  }
157 
158  body {
159    @apply bg-background text-foreground antialiased;
160  }
161}
162```
163 
164## Core Concepts
165 
166### 1. Design Token Hierarchy
167 
168```
169Brand Tokens (abstract)
170    └── Semantic Tokens (purpose)
171        └── Component Tokens (specific)
172 
173Example:
174    oklch(45% 0.2 260) → --color-primary → bg-primary
175```
176 
177### 2. Component Architecture
178 
179```
180Base styles → Variants → Sizes → States → Overrides
181```
182 
183## Detailed patterns and worked examples
184 
185Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
186 
187