Tailwind CSS v4: Architecture, CSS-First Configuration, and Container Queries

A CSS-First Evolution

Tailwind CSS v4 represents a significant evolution of the popular utility-first framework. The most notable change is the shift to a "CSS-first" configuration model. Instead of relying on a JavaScript configuration file (tailwind.config.js), all customizations—such as colors, fonts, spacing scales, and custom plugins—are now declared directly within a standard CSS entry file using the @theme directive.

This new compiler, called Lightningcss, processes CSS files with high performance and supports modern CSS features like container queries, native nested rules, and responsive design systems.

Setting Up Tailwind v4 CSS Configuration

In Tailwind v4, we define our design tokens inside our main CSS file. The JavaScript compiler parses these CSS variables and generates matching utilities automatically.

Here is an example setup for an app's global stylesheet:

@import "tailwindcss";

@theme {
  --font-display: "Clash Display", sans-serif;
  --font-sans: "Inter", sans-serif;
  
  --color-brand-primary: #f43f5e;
  --color-brand-dark: #0f172a;
  --color-accent: #6366f1;

  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  --breakpoint-xs: 480px;
}

@layer utilities {
  .clip-path-custom {
    clip-path: polygon(0 0, 100% 0, 85% 100%, 0% 100%);
  }
}

This configuration defines CSS custom properties that you can use in standard CSS, while Tailwind generates helper utility classes like bg-brand-primary, font-display, and p-18 automatically.

Native Container Queries

Tailwind v4 features built-in support for container queries. Container queries allow you to style elements based on the size of their parent container rather than the viewport size. This is useful for building responsive components that adapt depending on where they are placed in a layout (such as a sidebar vs. a main content area).

To implement container queries, mark the parent element as a container using the container-type class (or @container utility), and style children using @container variant modifiers:

<!-- Parent Container marked as layout container -->
<div class="@container bg-white/5 p-6 rounded-lg">
  <div class="flex flex-col @md:flex-row gap-6">
    <div class="flex-shrink-0 w-24 h-24 bg-accent/20 rounded-md"></div>
    <div>
      <!-- This heading changes size based on parent container width, not screen size -->
      <h3 className="text-lg font-bold @md:text-2xl">
        Responsive Component Heading
      </h3>
      <p className="text-gray-400 text-sm @md:text-base mt-2">
        This description adapts to container width, optimizing text wrapping and readability.
      </p>
    </div>
  </div>
</div>

In this example, @md: triggers only when the parent container's width exceeds 28rem (448px), regardless of whether the user is on a mobile device or a desktop monitor.

Performance and Modern Build Tools

By integrating with Lightningcss, Tailwind v4 compiles assets up to 10 times faster than v3. It generates smaller CSS files by removing unused rules and compiling outputs to clean CSS. As design systems adopt container-based layouts and CSS variables, Tailwind v4 provides a modern foundation for scaling web interfaces.