Tailwind CSS 4.0 Complete Guide 2026: New Features, Performance, and Migration

npm install tailwindcss@4 @tailwindcss/vite
# or
npm install tailwindcss@4 @tailwindcss/postcss

/* app/globals.css — CSS-first configuration */
@import "tailwindcss";

@theme {
  --font-display: "Inter", sans-serif;
  --color-brand: oklch(70% 0.2 240);
  --color-brand-dark: oklch(55% 0.2 240);
  --radius-card: 12px;
  --shadow-card: 0 4px 24px oklch(0% 0 0 / 0.1);
  --breakpoint-3xl: 1920px;
}

@import "tailwindcss";

@theme {
  /* Colors using OKLCH (perceptually uniform) */
  --color-primary-50: oklch(97% 0.02 250);
  --color-primary-100: oklch(93% 0.05 250);
  --color-primary-500: oklch(60% 0.2 250);
  --color-primary-900: oklch(25% 0.15 250);

  /* Custom fonts */
  --font-sans: "Inter Variable", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* Spacing scale */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom screens */
  --breakpoint-xs: 480px;
  --breakpoint-3xl: 1920px;

  /* Animations */
  --animate-shimmer: shimmer 2s linear infinite;
  --keyframes-shimmer: {
    to { background-position: 200% center; }
  };
}

<div class="text-primary-500 font-display pt-18 max-w-3xl">
  Custom theme values are instant utilities
</div>

<!-- @container queries without plugins -->
<div class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-2 @xl:grid-cols-4 gap-4">
    <ProductCard />
  </div>
</div>

<!-- Named containers -->
<aside class="@container/sidebar">
  <nav class="flex-col @sm/sidebar:flex-row flex gap-2">
    <!-- Changes layout based on sidebar's width, not viewport -->
  </nav>
</aside>

<!-- Tailwind 4: Any value with arbitrary syntax -->
<div class="grid-cols-[repeat(auto-fill,minmax(280px,1fr))]">
<div class="bg-[oklch(70%_0.15_250)]">
<div class="w-[clamp(200px,50vw,800px)]">
<div class="[--card-shadow:0_8px_32px_oklch(0%_0_0/0.15)]">

<!-- CSS variables as utilities -->
<div class="shadow-[var(--card-shadow)]">

<!-- 3D Transforms -->
<div class="rotate-x-45 rotate-y-12 translate-z-8 perspective-1000">
  3D card effect
</div>

<!-- Starting style for animations -->
<div class="transition-all @starting-style:opacity-0 @starting-style:translate-y-4">
  Animates in on mount
</div>

<!-- Field sizing (textarea auto-resize) -->
<textarea class="field-sizing-content"></textarea>

<!-- Color-mix -->
<div class="bg-[color-mix(in_oklch,theme(colors.blue.500),white_40%)]">

<!-- Inert (disable interaction) -->
<div class="inert:opacity-50 inert:pointer-events-none">

<!-- Not utility -->
<li class="not-[:first-child]:border-t">

<!-- Logical properties (RTL-aware) -->
<div class="ms-4 me-4 ps-6 pe-6">  <!-- margin/padding start/end -->

<!-- nth-child selectors -->
<li class="nth-[2n+1]:bg-gray-50">  <!-- odd rows -->
<li class="nth-last-2:font-bold">   <!-- 2nd from end -->

<!-- Has selector -->
<div class="has-[:checked]:ring-2">  <!-- when child is checked -->
<form class="has-[input:invalid]:border-red-500">

<!-- Group and peer enhancements -->
<div class="group/card hover:group-[.card]/card:shadow-xl">

<!-- In selector -->
<button class="in-[.dark-theme]:text-white in-[.light-theme]:text-black">

Tailwind v3: PostCSS pipeline → ~800ms cold build
Tailwind v4: Rust-powered   → ~80ms cold build (10x faster)
HMR:                        → ~5ms incremental updates

<!-- Card component -->
<article class="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm
                dark:border-gray-800 dark:bg-gray-900
                hover:shadow-md transition-shadow duration-200
                @container">
  <div class="flex flex-col @sm:flex-row gap-4">
    <img class="rounded-xl w-full @sm:w-48 h-48 object-cover" src="..." alt="" />
    <div class="flex flex-col gap-2">
      <span class="text-xs font-medium text-brand uppercase tracking-wide">Category</span>
      <h2 class="text-xl font-bold text-gray-900 dark:text-white">Title</h2>
      <p class="text-gray-600 dark:text-gray-400 line-clamp-3">Description...</p>
      <a href="#" class="mt-auto text-brand font-medium hover:underline">Read more →</a>
    </div>
  </div>
</article>

npx @tailwindcss/upgrade@next