# Tailwind Design System > Use this skill when building design systems with Tailwind CSS v4, configuring CSS-first themes, creating variant-based components, or migrating from Tailwind v3 to v4. - Skill: `ziadnagar/tailwind-design-system` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ziadnagar/tailwind-design-system` - Raw SKILL.md: https://api.skillmd.com/api/skills/ziadnagar/tailwind-design-system/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: Complete terms in LICENSE.txt - Author: ZiadNagar (https://skillmd.com/u/ziadnagar) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ziadnagar/tailwind-design-system --- # Tailwind Design System (v4) ## When to Use Apply this skill when the agent needs to: - Configure Tailwind CSS v4 with the new CSS-first `@theme` syntax - Build component libraries with CVA on top of Tailwind v4 - Implement dark mode with `@custom-variant` - Use OKLCH colors for perceptually uniform palettes - Create responsive grid systems with Tailwind utilities - Migrate an existing project from Tailwind v3 to v4 ## Key Concepts ### CSS-First Configuration Tailwind v4 replaces `tailwind.config.ts` with native CSS `@theme` blocks. Configuration lives in your CSS file, not JavaScript. ```css @import "tailwindcss"; @theme { --color-brand-50: oklch(0.97 0.01 250); --color-brand-100: oklch(0.93 0.02 250); --color-brand-200: oklch(0.87 0.04 250); --color-brand-300: oklch(0.78 0.08 250); --color-brand-400: oklch(0.68 0.12 250); --color-brand-500: oklch(0.55 0.16 250); --color-brand-600: oklch(0.47 0.16 250); --color-brand-700: oklch(0.4 0.14 250); --color-brand-800: oklch(0.33 0.11 250); --color-brand-900: oklch(0.25 0.08 250); --color-brand-950: oklch(0.18 0.06 250); --color-surface: oklch(0.99 0 0); --color-surface-alt: oklch(0.96 0 0); --color-on-surface: oklch(0.15 0 0); --color-on-surface-muted: oklch(0.45 0 0); --color-danger: oklch(0.55 0.2 25); --color-success: oklch(0.6 0.18 145); --color-warning: oklch(0.75 0.15 80); --font-family-sans: "Inter Variable", ui-sans-serif, system-ui, sans-serif; --font-family-mono: "JetBrains Mono Variable", ui-monospace, monospace; --spacing-content: 1rem; --spacing-section: 3rem; --radius-sm: 0.25rem; --radius-md: 0.5rem; --radius-lg: 0.75rem; --radius-xl: 1rem; --radius-full: 9999px; --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05); --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07), 0 2px 4px oklch(0 0 0 / 0.05); --shadow-lg: 0 10px 15px oklch(0 0 0 / 0.1), 0 4px 6px oklch(0 0 0 / 0.05); --animate-fade-in: fade-in 0.3s ease-out; --animate-slide-up: slide-up 0.3s ease-out; } @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } } @keyframes slide-up { from { opacity: 0; transform: translateY(0.5rem); } to { opacity: 1; transform: translateY(0); } } ``` ### OKLCH Color Space OKLCH provides perceptual uniformity — equal steps in lightness look equal to the human eye, unlike HSL. ``` oklch(L C H) L = Lightness (0–1): 0 is black, 1 is white C = Chroma (0–0.4): saturation intensity H = Hue (0–360): color wheel angle ``` Generate a palette by varying lightness while keeping chroma and hue constant: ```css @theme { --color-accent-100: oklch(0.93 0.1 300); --color-accent-300: oklch(0.78 0.15 300); --color-accent-500: oklch(0.55 0.2 300); --color-accent-700: oklch(0.4 0.15 300); --color-accent-900: oklch(0.25 0.08 300); } ``` ### Dark Mode with @custom-variant ```css @custom-variant dark (&:where(.dark, .dark *)); ``` This enables `dark:` utilities without additional JavaScript configuration. Toggle the `.dark` class on `` to switch themes. ## Patterns ### Complete Entry Point (app.css) ```css @import "tailwindcss"; @custom-variant dark (&:where(.dark, .dark *)); @theme { --color-brand-500: oklch(0.55 0.16 250); --color-brand-600: oklch(0.47 0.16 250); --color-surface: oklch(0.99 0 0); --color-surface-alt: oklch(0.96 0 0); --color-on-surface: oklch(0.15 0 0); --color-on-surface-muted: oklch(0.45 0 0); --color-border: oklch(0.9 0 0); --color-dark-surface: oklch(0.15 0 0); --color-dark-surface-alt: oklch(0.2 0 0); --color-dark-on-surface: oklch(0.93 0 0); --color-dark-on-surface-muted: oklch(0.6 0 0); --color-dark-border: oklch(0.3 0 0); --font-family-sans: "Inter Variable", system-ui, sans-serif; --radius-md: 0.5rem; --radius-lg: 0.75rem; } @layer base { :root { --background: var(--color-surface); --foreground: var(--color-on-surface); --muted: var(--color-on-surface-muted); --border: var(--color-border); } .dark { --background: var(--color-dark-surface); --foreground: var(--color-dark-on-surface); --muted: var(--color-dark-on-surface-muted); --border: var(--color-dark-border); } body { background-color: var(--background); color: var(--foreground); } } ``` ### CVA Button Component ```tsx import { cva, type VariantProps } from "class-variance-authority"; import { cn } from "@/lib/utils"; const buttonVariants = cva( "inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand-500 disabled:pointer-events-none disabled:opacity-50", { variants: { variant: { primary: "bg-brand-500 text-white hover:bg-brand-600 active:bg-brand-700", secondary: "bg-surface-alt text-on-surface border border-border hover:bg-surface-alt/80", ghost: "text-on-surface hover:bg-surface-alt", danger: "bg-danger text-white hover:opacity-90", link: "text-brand-500 underline-offset-4 hover:underline", }, size: { sm: "h-8 px-3 text-sm", md: "h-10 px-4 text-sm", lg: "h-12 px-6 text-base", icon: "h-10 w-10", }, }, defaultVariants: { variant: "primary", size: "md", }, }, ); interface ButtonProps extends React.ButtonHTMLAttributes, VariantProps {} export function Button({ className, variant, size, ...props }: ButtonProps) { return (