Tailwind CSS v4: The Oxide Engine, CSS-First Config, and Container Queries

CSS design patterns on a modern interface

Tailwind CSS v4 is a major architectural change. The entire engine has been rewritten in Rust (codenamed "Oxide"), the JavaScript configuration file has been replaced by CSS-based configuration using @theme, and the framework now leans heavily on modern CSS features like container queries, cascade layers, and color-mix().

The result is builds that are up to 10x faster, a configuration experience that feels more natural for CSS developers, and utilities for modern CSS features that previously required custom plugins.

CSS-First Configuration

The biggest workflow change is that tailwind.config.js is gone. Configuration now lives in your CSS file using the @theme directive:

app.css

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #6366f1;
  --font-sans: "Inter", sans-serif;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
}

Every design token is a CSS custom property. This means your theme values are available everywhere — in Tailwind classes, in custom CSS, and even in JavaScript via getComputedStyle. No more wondering whether a color is defined in your Tailwind config or your CSS variables.

The Oxide Engine

Tailwind v4's engine is rewritten in Rust and is dramatically faster. In benchmarks, full builds complete in under 100ms for most projects, and incremental rebuilds (when you change a class in a template) are nearly instantaneous.

The Oxide engine also enables features that weren't practical with the JavaScript-based scanner:

Automatic content detection — No more configuring content: [...] paths. Tailwind v4 automatically finds all your template files.
CSS-native processing — Tailwind v4 is a PostCSS plugin that processes CSS directly, rather than generating a separate utility stylesheet. This eliminates entire categories of build configuration issues.

Container Queries

Tailwind v4 adds native support for CSS container queries, which let you style elements based on the size of their container rather than the viewport:

Container query utilities

<!-- Define a container -->
<div class="@container">
  <!-- Respond to container width, not viewport -->
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
    <div class="p-4 bg-gray-100 rounded-lg">Card 1</div>
    <div class="p-4 bg-gray-100 rounded-lg">Card 2</div>
    <div class="p-4 bg-gray-100 rounded-lg">Card 3</div>
  </div>
</div>

Container queries are a game-changer for component-based design systems. A card component can now adapt its layout based on where it's placed — in a narrow sidebar, it stacks vertically; in a wide main content area, it uses a horizontal layout. The component doesn't need to know about the page layout, which is exactly how component architecture should work.

Other Notable Changes

Cascade layers — Tailwind v4 uses @layer to organize its output, giving you fine-grained control over specificity without !important hacks.
Color opacity modifier — The bg-blue-500/50 syntax now uses native color-mix() under the hood, producing more accurate colors.
No more arbitrary value brackets for spacing — Common spacing values are available as utilities without square brackets. p-4.5 just works.
Simplified dark mode — Dark mode uses the @media (prefers-color-scheme: dark) or [data-theme=dark] selectors by default, with cleaner output.

Migrating from v3

Tailwind provides an automated migration tool:

Terminal

npx @tailwindcss/upgrade

The tool converts your tailwind.config.js to CSS @theme directives, updates deprecated utility names, and adjusts your PostCSS configuration. Most projects migrate cleanly, but review the output for custom plugins (which may need manual conversion) and any utilities that changed names.

Note: If you're using a component library like shadcn/ui, check their documentation for v4-specific installation instructions — the configuration setup is different from v3.

Gerson