Tailwind CSS v4: What's New and Why It Matters

A New Engine Under the Hood

Tailwind CSS v4 is a ground-up rewrite. The new Oxide engine replaces the JavaScript-based PostCSS plugin with a high-performance Rust core, delivering build speeds up to 10x faster than v3. For large projects with thousands of utility classes, the difference is immediately noticeable.

But speed is just the beginning. The real story of v4 is a philosophical shift: CSS-first configuration.

CSS-First Configuration

Gone is tailwind.config.js. In v4, your design tokens live directly in your CSS using the @theme directive:

@import 'tailwindcss';

@theme {
  --color-bg-primary: #0d1117;
  --color-bg-secondary: #161b22;
  --color-accent-teal: #00adb5;
  --color-accent-rose: #e2725b;

  --font-heading: 'Poppins', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 4px 24px rgba(0, 0, 0, 0.3);
}

This approach has several advantages:

1. No context switching — Your design tokens are CSS custom properties, readable by any tool
2. No build step for config — Changes to tokens are picked up instantly by the dev server
3. Better IDE support — CSS files get syntax highlighting, autocomplete, and validation
4. Composability — Tokens can reference other tokens using standard CSS var() syntax

If you're migrating from v3, the `@tailwindcss/upgrade` CLI handles most of the conversion automatically. It reads your JavaScript config and generates the equivalent `@theme` block.

How We Structure Design Tokens

At Rosecraft Studios, we organize our @theme block into semantic categories:

@theme {
  /* === Colors === */
  --color-bg-primary: #0d1117;
  --color-bg-secondary: #161b22;
  --color-bg-card: #131920;

  --color-accent-teal: #00adb5;
  --color-accent-rose: #e2725b;
  --color-text-primary: #e6edf3;
  --color-text-muted: #8b949e;

  /* === Typography === */
  --font-heading: 'Poppins', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;

  /* === Shadows === */
  --shadow-card: 0 4px 24px rgba(0, 0, 0, 0.3);
  --shadow-teal-glow: 0 4px 16px rgba(0, 173, 181, 0.25);
}

Then in components, we use only the token names — never raw hex values:

<div className="bg-bg-card border border-border rounded-lg p-6">
  <h3 className="font-heading text-text-primary text-xl font-semibold">Card Title</h3>
  <p className="font-body text-text-muted">Card description</p>
</div>

This discipline pays off when a client requests a theme adjustment. Changing --color-accent-teal from #00adb5 to #0891b2 updates every component that uses it — instantly, with zero search-and-replace.

Automatic Content Detection

Tailwind v4 eliminates the content array configuration. The new engine automatically detects which files use utility classes:

/* v3: Required explicit content paths */
/* content: ['./src/**/*.{js,ts,jsx,tsx}'] */

/* v4: Just import and it works */
@import 'tailwindcss';

The Oxide scanner is fast enough to analyze your entire source tree in milliseconds. For monorepos, you can scope detection with @source directives:

@import 'tailwindcss';
@source "../shared/components";
@source "./src";

Container Queries Are Built In

Container queries — long a CSS wish-list feature — are first-class in v4:

<div className="@container">
  <div className="@sm:flex @sm:gap-4 @md:grid @md:grid-cols-3">
    {/* Layout responds to container width, not viewport */}
  </div>
</div>

Container queries are especially powerful for component libraries. A card component can adapt its layout based on the space available to it, regardless of where it's placed in the page.

Performance Impact

We benchmarked Tailwind v4 against v3 on a production project with 200+ components:

Metric	v3	v4	Change
Initial build	4.2s	0.8s	81% faster
Hot reload (single file)	340ms	45ms	87% faster
CSS output size	42 KB	38 KB	10% smaller
Dev server memory	180 MB	95 MB	47% less

The hot reload improvement is the most impactful for daily development. Saving a file and seeing the change in 45ms makes iterating on UI feel instantaneous.

Breaking Changes to Know About

The migration isn't entirely seamless. Key breaking changes:

Renamed Utilities

Some utility names changed for consistency:

/* v3 → v4 */
bg-opacity-50 → bg-black/50      /* Opacity modifiers replace separate classes */
ring-offset-2 → ring-offset-2    /* Unchanged, but implementation differs */
decoration-2 → decoration-2      /* Same class, CSS output changed */

Plugin API Changes

If you've written custom Tailwind plugins, the API has changed significantly. The plugin() function is replaced by CSS-native @plugin:

@plugin "./plugins/circuit-trace.css";

Dark Mode

Dark mode now uses the CSS light-dark() function by default instead of class-based toggling. For projects that need class-based dark mode (like theme toggles), explicit configuration is still available.

Our Recommendation

For new projects, Tailwind v4 is the clear choice. The faster builds, CSS-first configuration, and built-in features like container queries make it superior to v3 in every measurable way.

For existing v3 projects, we recommend migrating when you have a natural refactoring window. The @tailwindcss/upgrade tool handles 90% of the work, but you'll want to allocate time for testing visual regressions.

Need help with a Tailwind v4 migration or building a design system? Reach out — we've done this for multiple production applications and know where the gotchas are.