Builds production-ready design systems with Tailwind CSS v4 using CSS-first configuration, design tokens, CVA component variants, and native CSS animations. Use this skill when creating component libraries, implementing design tokens with @theme, setting up dark mode with @custom-variant, migrating from Tailwind v3 to v4, building type-safe component variants, or standardizing UI patterns across a codebase. Apply when you see tailwind.config.ts, @tailwind directives, or any Tailwind-related question — v4 changes the setup significantly.
Builds production-ready design systems with Tailwind CSS v4 using CSS-first configuration, design tokens, CVA component variants, and native CSS animations. Use this skill when creating component libraries, implementing design tokens with @theme, setting up dark mode with @custom-variant, migrating from Tailwind v3 to v4, building type-safe component variants, or standardizing UI patterns across a codebase. Apply when you see tailwind.config.ts, @tailwind directives, or any Tailwind-related question — v4 changes the setup significantly.
Tailwind Design System
Tailwind v4 is a rewrite. The config file is gone — everything moves to CSS. This isn't just an API change; it's a shift in mental model: design tokens live in your CSS, not a JavaScript object. The result is faster builds, better tree-shaking, and CSS-native patterns (custom properties, cascade layers, container queries) without workarounds.
When to Use This Skill
Starting a new project with Tailwind CSS
Migrating from Tailwind v3 to v4
Building a component library that needs type-safe variants
Implementing a design token system
Setting up dark mode that works with server-rendered apps
Workflow
Set up the CSS entry point — @import "tailwindcss" and @theme block
Define the token hierarchy — Brand → Semantic → Component
Configure dark mode — @custom-variant dark
Set up CVA — for component variants
Add the cn() utility — for conditional class merging
Define animations — @keyframes inside @theme
Core Setup: CSS-First Configuration
Tailwind v4 is configured entirely in CSS. There is no .
Components use component tokens; never use brand tokens directly in components.
OKLCH Colors
Use OKLCH (oklch(L% C H)) instead of hex codes for perceptually uniform color scales. OKLCH produces palettes where each step is visually equal distance apart, unlike hex-based palettes.
Define dark mode using @custom-variant to support both system preference and manual toggle.
/* Supports class-based dark mode: */@custom-variant dark (&:where(.dark, .dark *));
/* Or system preference only: */@custom-variant dark (@media (prefers-color-scheme: dark));
Then override semantic tokens in the dark context:
.dark {
--color-background: oklch(10%0.01250);
--color-foreground: oklch(95%0.01250);
--color-border: oklch(25%0.02250);
--color-primary: oklch(65%0.2250); /* lighter for dark bg */
}
Set up the cn() utility for conditional class merging. It combines clsx (conditional classes) with tailwind-merge (deduplicates conflicting Tailwind classes).
