Tailwind CSS v4

CSS-First Configuration

v4 eliminates tailwind.config.ts. All configuration lives in CSS.

Directive	Purpose
`@import "tailwindcss"`	Entry point (replaces `@tailwind base/components/utilities`)
`@theme { }`	Define/extend design tokens — auto-generates utility classes
`@theme inline { }`	Map CSS variables to Tailwind utilities without generating new vars
`@theme static { }`	Define tokens that don't generate utilities
`@utility name { }`	Create custom utilities (replaces `@layer components` + `@apply`)
`@custom-variant name (selector)`	Define custom variants

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --animate-fade-in: fade-in 0.2s ease-out;
  @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
}

@custom-variant dark (&:where(.dark, .dark *));

Tokens defined with @theme become utilities automatically: --color-brand produces bg-brand, text-brand, border-brand.

v3 to v4 Breaking Changes

v3	v4	Notes
`tailwind.config.ts`	`@theme` in CSS	Delete config file
`@tailwind base/components/utilities`	`@import "tailwindcss"`	Single import
`darkMode: "class"`	`@custom-variant dark (...)`	CSS-only
`bg-gradient-to-r`	`bg-linear-to-r`	Also: `bg-radial`, `bg-conic`
`bg-opacity-60`	`bg-red-500/60`	All `-opacity-` removed
`rounded-md` (6px)	`rounded` (6px)	Radius scale shifted down
`min-h-screen`	`min-h-dvh`	`dvh` handles mobile browser chrome
`w-6 h-6`	`size-6`	Size shorthand for equal w/h
`space-x-4`	`gap-4`	Gap handles flex/grid wrapping correctly
`text-base leading-7`	`text-base/7`	Inline line-height modifier
`require("tailwindcss-animate")`	`tw-animate-css`	CSS-only animations
`forwardRef`	`ref` as prop	React 19 change (not Tailwind, but co-occurs)

Coding Rules

gap over space-x/space-y — gap handles wrapping; space-* breaks on wrap
size-* over w-* h-* — for equal dimensions
min-h-dvh over min-h-screen — dvh accounts for mobile browser chrome
Opacity modifier (bg-black/50) — *-opacity-* utilities are removed in v4
Design tokens over arbitrary values — check @theme before using [#hex]
Never construct classes dynamically — text-${color}-500 won't be detected; use complete class names
@utility over @apply with @layer — @apply on @layer classes fails in v4

Class Merging

Use cn() combining clsx + tailwind-merge for conditional/dynamic classes. Use plain strings for static className attributes.

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }

// Static: plain string
<button className="rounded-lg px-4 py-2 font-medium bg-blue-600">

// Conditional: use cn()
<button className={cn("rounded-lg px-4 py-2", isActive ? "bg-blue-600" : "bg-gray-700")} />

Component Variants

Use tailwind-variants (tv()) for type-safe variant components. Alternative: class-variance-authority (cva()).

import { tv } from "tailwind-variants";
const button = tv({
  base: "rounded-lg px-4 py-2 font-medium transition-colors",
  variants: {
    color: { primary: "bg-blue-600 text-white", secondary: "bg-gray-200 text-gray-800" },
    size: { sm: "text-sm px-3 py-1", md: "text-base", lg: "text-lg px-6 py-3" },
  },
  defaultVariants: { color: "primary", size: "md" },
});

See tailwind-variants patterns for slots, composition, and responsive variants.

Common Errors

Symptom	Fix
`bg-primary` doesn't work	Add `@theme inline { --color-primary: var(--primary); }`
Colors all black/white	Double `hsl()` wrapping — use `var(--color)` not `hsl(var(--color))`
`@apply` fails on custom class	Use `@utility` instead of `@layer components`
Build fails after migration	Delete `tailwind.config.ts`
Animations broken	Replace `tailwindcss-animate` with `tw-animate-css`
`.dark { @theme { } }` fails	v4 does not support nested `@theme` — use `:root`/`.dark` CSS vars mapped via `@theme inline`

Dark Mode (v4 Pattern)

:root { --background: hsl(0 0% 100%); --foreground: hsl(222 84% 4.9%); }
.dark { --background: hsl(222 84% 4.9%); --foreground: hsl(210 40% 98%); }
@theme inline { --color-background: var(--background); --color-foreground: var(--foreground); }

Semantic classes (bg-background, text-foreground) auto-switch — no dark: variants needed for themed colors.

References

Component patterns — tailwind-variants slots, CVA, compound components
Layout patterns — grid areas, container queries, z-index management, fluid typography

tailwind-css