What Is Tailwind CSS v4? — Next Generation CSS Framework

In this tutorial, you will learn about What Is Tailwind CSS v4?. We cover key concepts, practical examples, and best practices to help you master this topic.

Tailwind CSS v4 is a ground-up rebuild of Tailwind CSS using the Lightning CSS engine, featuring CSS-first configuration, unified variants, native container queries, and zero-config setup.

What You'll Learn

You will learn what changed in Tailwind v4, the new CSS-first configuration approach, unified variant syntax, container query support, and how the Lightning CSS engine improves performance.

Why It Matters

Tailwind v4 reduces setup complexity and improves developer experience. DodaTech upgraded to v4 for Doda Browser's extension, cutting config file size by 60 percent and improving build times by 2x.

Real-World Use

DodaZIP's marketing site uses Tailwind v4's CSS-first config for theme customization, container queries for responsive widgets, and unified variants throughout the component library.

flowchart LR
    A[Tailwind v3] --> B[Tailwind v4]
    B --> C[CSS-First Config]
    B --> D[Unified Variants]
    B --> E[Container Queries]
    B --> F[Lightning CSS]
    style B fill:#38bdf8,stroke:#0284c7,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

CSS-First Configuration

In v4, Tailwind configuration moves from JavaScript to CSS using the @theme directive:

/* tailwind v4 CSS-first config */
@import "tailwindcss";

@theme {
  --color-brand-50: #f5f3ff;
  --color-brand-100: #ede9fe;
  --color-brand-500: #7c3aed;
  --color-brand-600: #6d28d9;
  --color-brand-700: #5b21b6;

  --font-family-display: "Inter", sans-serif;

  --spacing-page: 2rem;
}

Expected output: Tailwind v4 reads CSS custom properties from @theme and generates utility classes automatically. No tailwind.config.js needed for most projects.

Unified Variant Syntax

/* v3: separate syntax for each variant type */
@variants hover, focus, dark { }

/* v4: unified variant syntax */
@variant hover {
  .btn-primary {
    background: var(--color-brand-600);
  }
}

<!-- v3: prefixes on utilities -->
<button class="hover:bg-blue-700 dark:bg-blue-500 md:text-lg">Button</button>

<!-- v4: same prefix syntax (backward compatible) -->
<button class="hover:bg-brand-700 dark:bg-brand-500 md:text-lg">Button</button>

Expected output: The familiar variant prefix syntax remains the same. New @variant directive enables CSS-based variant definitions.

Native Container Queries

/* v4: built-in container query support */
@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

<div class="@container max-w-md">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 gap-4">
    <div class="bg-blue-100 p-4 rounded">Item 1</div>
    <div class="bg-blue-200 p-4 rounded">Item 2</div>
    <div class="bg-blue-300 p-4 rounded">Item 3</div>
  </div>
</div>

Expected output: Container queries work natively in v4. Use @sm:, @md:, @lg: prefixes for container-based responsive styles.

Lightning CSS Engine

# v3: PostCSS-based
npm install tailwindcss postcss

# v4: Lightning CSS-based (faster, bundled)
npm install tailwindcss @tailwindcss/vite

Expected output: Lightning CSS provides 10-100x faster Parsing and transformation compared to the old PostCSS-based pipeline.

Common Mistakes

1. Using tailwind.config.js in v4 Projects

v4 uses @theme in CSS for configuration. The old JavaScript config file is no longer the primary configuration method.

2. Expecting PostCSS Plugins to Work

v4 replaces PostCSS with Lightning CSS. PostCSS plugins for Tailwind (like autoprefixer) are handled internally.

3. Not Using the New Package Name

npm install tailwindcss @tailwindcss/vite installs v4. The old @tailwindcss/postcss package is for v3 compatibility.

4. Forgetting @import "tailwindcss"

The @import "tailwindcss" statement is required in your main CSS file for v4 to Process utilities.

5. Confusing @theme with @apply

@theme defines design tokens. @apply composes utilities. They serve different purposes in v4.

Practice Questions

1. What is the main architecture change in v4? CSS-first configuration via @theme instead of JavaScript config files. Lightning CSS replaces PostCSS.

2. How do you define custom colors in v4? Using @theme { --color-*: value; } in your CSS file.

3. Are container queries built in? Yes. v4 has native container query support with @Container and @sm:, @md:, @lg: prefixes.

4. What replaced PostCSS? Lightning CSS -- a Rust-based CSS engine that is 10-100x faster.

5. Is the variant prefix syntax different? No. hover:, focus:, dark:, md:, etc. work the same way as v3.

Challenge

Set up a new Tailwind v4 project using @import "tailwindcss" in the CSS file, define 3 custom colors using @theme, and container queries using @sm: prefix. Verify it builds.

FAQ

Mini Project

Migrate a simple v3 project to v4: replace tailwind.config.js with @theme in CSS, switch from PostCSS to Vite/Tailwind CLI, verify all utilities work, and test container queries.

What's Next

Proceed to Migration from v3 for a detailed upgrade guide. Then explore CSS-First Configuration for the new setup approach.