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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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).
