Tailwind CSS v4: CSS-First Configuration Explained
Tailwind CSS v4 moves configuration into your CSS with @theme. How to install it in Next.js, define colors and fonts as tokens, and migrate from v3.
By UndieGravity, , 1 min read
Tailwind CSS v4 changed where configuration lives. Instead of a tailwind.config.js file, you define your design tokens in CSS with an @theme block. Every token becomes both a utility class and a regular CSS variable you can use anywhere.
Install in a Next.js project
npm install tailwindcss @tailwindcss/postcss// postcss.config.mjs
export default {
plugins: { "@tailwindcss/postcss": {} },
};/* app/globals.css */
@import "tailwindcss";That single import replaces the three @tailwind directives from v3. Tailwind finds your class names automatically, so there is no content array to maintain.
Define your design tokens
@theme {
--color-surface: #ffffff;
--color-text: #18181b;
--color-accent: #3f3cf2;
--font-sans: var(--font-inter), system-ui, sans-serif;
--radius-lg: 1rem;
}Now bg-accent, text-text, font-sans, and rounded-lg use your values, and var(--color-accent) works in any CSS file or inline style.
Why tokens beat raw colors
If components use bg-accent instead of bg-indigo-600, changing the brand color is a one line edit. This is the fastest way to customize a template: change the tokens and the whole site follows.
Custom utilities and animations
@theme {
--animate-fade-in: fade-in 200ms ease-out;
@keyframes fade-in {
from { opacity: 0; }
to { opacity: 1; }
}
}This gives you an animate-fade-in class with the keyframes defined next to it.
Migrating from v3
- Run the official upgrade tool:
npx @tailwindcss/upgrade. It moves your config into CSS and renames changed classes. - Check renamed utilities, for example the shadow and blur scales shifted, so
shadow-smin v3 isshadow-xsin v4. - Remove
tailwind.config.jsonce everything is in@theme. - Test focus rings and borders; default colors for some utilities changed.
Browser support
v4 relies on modern CSS features such as cascade layers and @property, so it targets current browsers (Safari 16.4 and newer, Chrome and Firefox of the last few years). If you must support older browsers, stay on v3.