Migrating to Tailwind CSS v4: Moving from JavaScript Config to Native CSS Cascade Layers
How Tailwind CSS v4 replaces tailwind.config.js with the native @theme directive, improves bundle speeds with Lightning CSS, and organizes studio design tokens.
Akusara Design Team
Design Systems & UI
How Tailwind CSS v4 replaces tailwind.config.js with the native @theme directive, improves bundle speeds with Lightning CSS, and organizes studio design tokens.
What Changed in Tailwind CSS v4
For years, tailoring a design system in Tailwind meant configuring a complex tailwind.config.js object. You mapped fonts, colors, breakpoints, and plugins in JavaScript, which PostCSS transformed into utility classes.
In Tailwind CSS v4, the configuration model is fundamentally CSS-native. The JavaScript configuration file is replaced by the @theme directive inside your primary CSS file.
CSS-First Token Configuration
Here is how our studio palette is declared directly in app/globals.css:
@import "tailwindcss";
@theme {
--color-navy-950: #080d1a;
--color-navy-900: #0f1e3d;
--color-navy-800: #172a54;
--color-blue-600: #2563eb;
--color-blue-500: #3b82f6;
--color-blue-50: #eff6ff;
--font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
}The Benefits in Production
- Lightning CSS Compiler:
Tailwind v4 is built on an Rust-powered engine that compiles stylesheets in single-digit milliseconds during development.
- Zero JavaScript Config Layer:
No more desynchronization between JavaScript theme tokens and native CSS custom properties. Every variable defined in @theme is automatically available as both a utility class (e.g. bg-navy-900) and a native CSS variable (var(--color-navy-900)).
- True Cascade Layering:
Native @layer integration means specificity battles between custom styling and framework utilities are resolved according to standard CSS specification rules.
Recommendation
If you are starting a new Next.js project today, adopt Tailwind CSS v4 with PostCSS. The simplicity of having design tokens defined directly in CSS pays dividends in codebase legibility.
Published by Akusara Design Team
Design Systems & UI
Akusara Digital is an engineering and product studio building mission-critical software, custom SaaS platforms, and developer tooling.
Read Next from Akusara
All ArticlesBeyond AI Slop: Why Purpose-Driven Design Wins Over Generic Templates
Why modern creative agencies must abandon generic corporate AI templates, decorative gradients without purpose, and corporate buzzwords.

Synthesizing Automated Test Suites: How SnapTest Generates Playwright Specs from DOM Snapshots
How our in-house test generator parses live DOM trees, generates resilient accessible role selectors, and outputs ready-to-run Playwright tests without fragile XPath locators.
