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## Patterns
184 
185### Pattern 1: CVA (Class Variance Authority) Components
186 
187```typescript
188// components/ui/button.tsx
189import { Slot } from '@radix-ui/react-slot'
190import { cva, type VariantProps } from 'class-variance-authority'
191import { cn } from '@/lib/utils'
192 
193const buttonVariants = cva(
194  // Base styles - v4 uses native CSS variables
195  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
196  {
197    variants: {
198      variant: {
199        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
200        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
201        outline: 'border border-border bg-background hover:bg-accent hover:text-accent-foreground',
202        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
203        ghost: 'hover:bg-accent hover:text-accent-foreground',
204        link: 'text-primary underline-offset-4 hover:underline',
205      },
206      size: {
207        default: 'h-10 px-4 py-2',
208        sm: 'h-9 rounded-md px-3',
209        lg: 'h-11 rounded-md px-8',
210        icon: 'size-10',
211      },
212    },
213    defaultVariants: {
214      variant: 'default',
215      size: 'default',
216    },
217  }
218)
219 
220export interface ButtonProps
221  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
222    VariantProps<typeof buttonVariants> {
223  asChild?: boolean
224}
225 
226// React 19: No forwardRef needed
227export function Button({
228  className,
229  variant,
230  size,
231  asChild = false,
232  ref,
233  ...props
234}: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
235  const Comp = asChild ? Slot : 'button'
236  return (
237    <Comp
238      className={cn(buttonVariants({ variant, size, className }))}
239      ref={ref}
240      {...props}
241    />
242  )
243}
244 
245// Usage
246<Button variant="destructive" size="lg">Delete</Button>
247<Button variant="outline">Cancel</Button>
248<Button asChild><Link href="/home">Home</Link></Button>
249```
250 
251### Pattern 2: Compound Components (React 19)
252 
253```typescript
254// components/ui/card.tsx
255import { cn } from '@/lib/utils'
256 
257// React 19: ref is a regular prop, no forwardRef
258export function Card({
259  className,
260  ref,
261  ...props
262}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
263  return (
264    <div
265      ref={ref}
266      className={cn(
267        'rounded-lg border border-border bg-card text-card-foreground shadow-sm',
268        className
269      )}
270      {...props}
271    />
272  )
273}
274 
275export function CardHeader({
276  className,
277  ref,
278  ...props
279}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
280  return (
281    <div
282      ref={ref}
283      className={cn('flex flex-col space-y-1.5 p-6', className)}
284      {...props}
285    />
286  )
287}
288 
289export function CardTitle({
290  className,
291  ref,
292  ...props
293}: React.HTMLAttributes<HTMLHeadingElement> & { ref?: React.Ref<HTMLHeadingElement> }) {
294  return (
295    <h3
296      ref={ref}
297      className={cn('text-2xl font-semibold leading-none tracking-tight', className)}
298      {...props}
299    />
300  )
301}
302 
303export function CardDescription({
304  className,
305  ref,
306  ...props
307}: React.HTMLAttributes<HTMLParagraphElement> & { ref?: React.Ref<HTMLParagraphElement> }) {
308  return (
309    <p
310      ref={ref}
311      className={cn('text-sm text-muted-foreground', className)}
312      {...props}
313    />
314  )
315}
316 
317export function CardContent({
318  className,
319  ref,
320  ...props
321}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
322  return (
323    <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
324  )
325}
326 
327export function CardFooter({
328  className,
329  ref,
330  ...props
331}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
332  return (
333    <div
334      ref={ref}
335      className={cn('flex items-center p-6 pt-0', className)}
336      {...props}
337    />
338  )
339}
340 
341// Usage
342<Card>
343  <CardHeader>
344    <CardTitle>Account</CardTitle>
345    <CardDescription>Manage your account settings</CardDescription>
346  </CardHeader>
347  <CardContent>
348    <form>...</form>
349  </CardContent>
350  <CardFooter>
351    <Button>Save</Button>
352  </CardFooter>
353</Card>
354```
355 
356### Pattern 3: Form Components
357 
358```typescript
359// components/ui/input.tsx
360import { cn } from '@/lib/utils'
361 
362export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
363  error?: string
364  ref?: React.Ref<HTMLInputElement>
365}
366 
367export function Input({ className, type, error, ref, ...props }: InputProps) {
368  return (
369    <div className="relative">
370      <input
371        type={type}
372        className={cn(
373          'flex h-10 w-full rounded-md border border-border bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
374          error && 'border-destructive focus-visible:ring-destructive',
375          className
376        )}
377        ref={ref}
378        aria-invalid={!!error}
379        aria-describedby={error ? `${props.id}-error` : undefined}
380        {...props}
381      />
382      {error && (
383        <p
384          id={`${props.id}-error`}
385          className="mt-1 text-sm text-destructive"
386          role="alert"
387        >
388          {error}
389        </p>
390      )}
391    </div>
392  )
393}
394 
395// components/ui/label.tsx
396import { cva, type VariantProps } from 'class-variance-authority'
397 
398const labelVariants = cva(
399  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
400)
401 
402export function Label({
403  className,
404  ref,
405  ...props
406}: React.LabelHTMLAttributes<HTMLLabelElement> & { ref?: React.Ref<HTMLLabelElement> }) {
407  return (
408    <label ref={ref} className={cn(labelVariants(), className)} {...props} />
409  )
410}
411 
412// Usage with React Hook Form + Zod
413import { useForm } from 'react-hook-form'
414import { zodResolver } from '@hookform/resolvers/zod'
415import { z } from 'zod'
416 
417const schema = z.object({
418  email: z.string().email('Invalid email address'),
419  password: z.string().min(8, 'Password must be at least 8 characters'),
420})
421 
422function LoginForm() {
423  const { register, handleSubmit, formState: { errors } } = useForm({
424    resolver: zodResolver(schema),
425  })
426 
427  return (
428    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
429      <div className="space-y-2">
430        <Label htmlFor="email">Email</Label>
431        <Input
432          id="email"
433          type="email"
434          {...register('email')}
435          error={errors.email?.message}
436        />
437      </div>
438      <div className="space-y-2">
439        <Label htmlFor="password">Password</Label>
440        <Input
441          id="password"
442          type="password"
443          {...register('password')}
444          error={errors.password?.message}
445        />
446      </div>
447      <Button type="submit" className="w-full">Sign In</Button>
448    </form>
449  )
450}
451```
452 
453### Pattern 4: Responsive Grid System
454 
455```typescript
456// components/ui/grid.tsx
457import { cn } from '@/lib/utils'
458import { cva, type VariantProps } from 'class-variance-authority'
459 
460const gridVariants = cva('grid', {
461  variants: {
462    cols: {
463      1: 'grid-cols-1',
464      2: 'grid-cols-1 sm:grid-cols-2',
465      3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
466      4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
467      5: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-5',
468      6: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-6',
469    },
470    gap: {
471      none: 'gap-0',
472      sm: 'gap-2',
473      md: 'gap-4',
474      lg: 'gap-6',
475      xl: 'gap-8',
476    },
477  },
478  defaultVariants: {
479    cols: 3,
480    gap: 'md',
481  },
482})
483 
484interface GridProps
485  extends React.HTMLAttributes<HTMLDivElement>,
486    VariantProps<typeof gridVariants> {}
487 
488export function Grid({ className, cols, gap, ...props }: GridProps) {
489  return (
490    <div className={cn(gridVariants({ cols, gap, className }))} {...props} />
491  )
492}
493 
494// Container component
495const containerVariants = cva('mx-auto w-full px-4 sm:px-6 lg:px-8', {
496  variants: {
497    size: {
498      sm: 'max-w-screen-sm',
499      md: 'max-w-screen-md',
500      lg: 'max-w-screen-lg',
501      xl: 'max-w-screen-xl',
502      '2xl': 'max-w-screen-2xl',
503      full: 'max-w-full',
504    },
505  },
506  defaultVariants: {
507    size: 'xl',
508  },
509})
510 
511interface ContainerProps
512  extends React.HTMLAttributes<HTMLDivElement>,
513    VariantProps<typeof containerVariants> {}
514 
515export function Container({ className, size, ...props }: ContainerProps) {
516  return (
517    <div className={cn(containerVariants({ size, className }))} {...props} />
518  )
519}
520 
521// Usage
522<Container>
523  <Grid cols={4} gap="lg">
524    {products.map((product) => (
525      <ProductCard key={product.id} product={product} />
526    ))}
527  </Grid>
528</Container>
529```
530 
531For advanced animation and dark mode patterns, see [references/advanced-patterns.md](references/advanced-patterns.md):
532 
533- **Pattern 5: Native CSS Animations** — dialog `@keyframes`, native popover API with `@starting-style`, `allow-discrete` transitions, and a full `DialogContent`/`DialogOverlay` implementation using Radix UI
534- **Pattern 6: Dark Mode** — `ThemeProvider` context with `localStorage` persistence, `prefers-color-scheme` detection, meta `theme-color` update, and a `ThemeToggle` button component
535 
536## Utility Functions
537 
538```typescript
539// lib/utils.ts
540import { type ClassValue, clsx } from "clsx";
541import { twMerge } from "tailwind-merge";
542 
543export function cn(...inputs: ClassValue[]) {
544  return twMerge(clsx(inputs));
545}
546 
547// Focus ring utility
548export const focusRing = cn(
549  "focus-visible:outline-none focus-visible:ring-2",
550  "focus-visible:ring-ring focus-visible:ring-offset-2",
551);
552 
553// Disabled utility
554export const disabled = "disabled:pointer-events-none disabled:opacity-50";
555```
556 
557For advanced v4 CSS patterns, the full v3-to-v4 migration checklist, and complete best practices, see [references/advanced-patterns.md](references/advanced-patterns.md):
558 
559- **Custom `@utility`** — reusable CSS utilities for decorative lines and text gradients
560- **Theme modifiers** — `@theme inline` (reference other CSS vars), `@theme static` (always output), `@import "tailwindcss" theme(static)`
561- **Namespace overrides** — clearing default Tailwind color scales with `--color-*: initial`
562- **Semi-transparent variants** — `color-mix()` for alpha scale generation
563- **Container queries** — `--container-*` token definitions
564- **v3→v4 migration checklist** — 10-item checklist covering config, directives, colors, dark mode, animations, React 19 ref changes
565- **Best practices** — full Do's and Don'ts list
566