UndieGravity LogoUndiegravity

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

  1. Run the official upgrade tool: npx @tailwindcss/upgrade. It moves your config into CSS and renames changed classes.
  2. Check renamed utilities, for example the shadow and blur scales shifted, so shadow-sm in v3 is shadow-xs in v4.
  3. Remove tailwind.config.js once everything is in @theme.
  4. 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.

Keep reading

HTML and CSS

CSS Grid vs Flexbox: When to Use Each

Flexbox lays out items in one direction; CSS Grid lays out rows and columns together. Real examples of navbars, card grids, and page layouts with each.

, 1 min read