Tailwind CSS v4 is not an incremental update. It is a full rewrite of the engine with a fundamentally different configuration model. If you have been using Tailwind since v2 or v3, some of these changes will feel unfamiliar at first. They are all improvements.
CSS-First Configuration
The biggest shift: tailwind.config.js is gone. Configuration now lives in your CSS file using the @theme directive.
@import "tailwindcss";
@theme {
--color-primary: oklch(0.7 0.15 240);
--color-secondary: oklch(0.5 0.1 280);
--font-sans: "Inter", sans-serif;
--font-heading: "Cal Sans", sans-serif;
--spacing-18: 4.5rem;
--breakpoint-3xl: 120rem;
}This is not just a syntax change. Moving configuration into CSS means:
- No JavaScript tooling required to process your design tokens
- Native CSS cascade applies to your theme values
- IDE support works out of the box since it is standard CSS
- Build times drop significantly because there is no config file to evaluate
Your theme tokens become CSS custom properties automatically. --color-primary generates the utility class text-primary, bg-primary, border-primary, and every other color utility. No mapping, no configuration objects, no plugin system.
OKLCH Colors
Tailwind v4 uses OKLCH as its default color space. If you have not encountered OKLCH before, it is a perceptually uniform color space. That means a lightness value of 0.7 looks equally bright whether the hue is blue, green, or red.
This solves a real problem. In hex or HSL, creating a set of colors that feel visually consistent requires manual tuning. In OKLCH, you adjust lightness and chroma independently and the results are predictable.
@theme {
--color-brand-50: oklch(0.97 0.02 240);
--color-brand-100: oklch(0.93 0.04 240);
--color-brand-200: oklch(0.87 0.08 240);
--color-brand-500: oklch(0.65 0.18 240);
--color-brand-900: oklch(0.25 0.10 240);
}Every step in this scale has consistent visual spacing. The hue stays locked at 240, and you only vary lightness and chroma. Building a cohesive color palette becomes a formula instead of a guessing game.
Container Queries
Tailwind v4 ships with first-class container query support. This is a significant upgrade for component-based design.
<div class="@container">
<div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
<div class="p-4">Card content</div>
<div class="p-4">Card content</div>
<div class="p-4">Card content</div>
</div>
</div>The @container class marks an element as a container query context. The @md: and @lg: prefixes respond to the container’s width, not the viewport. This means a card component can adapt its layout based on where it is placed, not what screen size the user has.
For marketing sites with flexible grid layouts, sidebar content areas, and reusable card components, this eliminates the most common source of responsive design hacks.
Faster Builds
The v4 engine is written in Rust and processes CSS significantly faster than v3. On large codebases, build times can drop by 5-10x. On typical marketing sites, the difference is less dramatic but still noticeable, especially during development where hot module replacement feels nearly instant.
The performance improvement comes from multiple changes:
- No JavaScript config evaluation at build time
- Oxide engine written in Rust for CSS parsing and generation
- Smarter class detection that reduces the work done on each rebuild
What Changed From v3
A few things to watch for if you are migrating:
Dark mode now uses the @dark variant internally, but the dark: prefix in your HTML works the same way. The underlying mechanism switched from a class-based toggle to prefers-color-scheme by default, with an opt-in for class-based control.
Arbitrary values use the same bracket syntax: w-[300px], text-[#ff0000]. No changes here.
Plugins are replaced by CSS-native @utility and @variant directives:
@utility tab-4 {
tab-size: 4;
}
@variant hocus (&:hover, &:focus);This is cleaner than the v3 plugin API and does not require JavaScript.
The @apply directive still works but is discouraged for new code. The recommendation is to use component abstractions in your framework instead of CSS-level composition.
How Astro Starter Uses v4
Astro Starter ships with Tailwind v4 configured out of the box. The theme is defined in a tokens.css file using the @theme directive, with OKLCH color values for the primary, secondary, accent, and muted palettes. The design system uses CSS custom properties throughout, making it straightforward to rebrand the entire site by changing a handful of color values.
The template avoids @apply entirely. All styling is done with utility classes in the HTML, following the Tailwind philosophy of colocating styles with markup. Component variants are handled through Astro component props and conditional class rendering with the cn() utility.
If you are starting a new project in 2025, there is no reason to use Tailwind v3. The v4 developer experience is better in every measurable way, and the CSS-first configuration model is the direction the ecosystem is heading.
