What is Tailwind CSS v4?

Tailwind CSS v4, released in early 2025, is a ground-up rewrite of the framework. The headline changes are a new high-performance engine, CSS-first configuration, automatic source detection and a design built on modern CSS: cascade layers, registered custom properties, color-mix() and container queries. Most utility class names carry over from v3, so reading v4 code feels familiar; the setup and customization model is what changed.

How it works

There is no tailwind.config.js by default. You import Tailwind in your CSS and define theme values with @theme. Each theme variable generates utilities and is also emitted as a normal CSS variable you can read anywhere. Build integration comes through @tailwindcss/vite, @tailwindcss/postcss or the CLI.

@import "tailwindcss";

@theme {
  --color-accent: oklch(0.53 0.215 283);
  --font-sans: "Geist", ui-sans-serif, system-ui, sans-serif;
  --radius-card: 12px;
}

@custom-variant dark (&:is(.dark *));

@utility bg-grid {
  background-image: linear-gradient(to right, oklch(0.2 0.02 264 / 0.06) 1px, transparent 1px);
  background-size: 48px 48px;
}

That file gives you bg-accent, text-accent, font-sans and rounded-card, a class-based dark: variant, and a custom bg-grid utility. The main directives:

• @theme defines design tokens in namespaces (--color-*, --font-*, --spacing, --radius-*, --shadow-*) that generate utilities. @theme inline makes utilities use a referenced variable directly, which is how you map existing CSS variables into Tailwind.
• @source adds paths that automatic detection skips, such as a component package in node_modules.
• @custom-variant and @utility replace plugin code for most custom variants and utilities.
• @plugin and @config still load JavaScript plugins and legacy config files when you need them.

Migrating from v3

The official npx @tailwindcss/upgrade tool handles most of a v3 project. Check a few things by hand: several scales shifted by one step (for example shadow-sm became shadow-xs and rounded-sm became rounded-xs), the default border color is now currentColor, and dark: follows prefers-color-scheme unless you redefine it. v4 targets modern browsers (Safari 16.4, Chrome 111 and Firefox 128 or newer), so projects that must support older browsers should stay on v3.4.

How MiniDev UI uses it

MiniDev UI is written for Tailwind CSS v4 only. Its stylesheet defines tokens as CSS variables in OKLCH, maps them with @theme inline, adds signature utilities like bg-grid and bg-dots with @utility, and sets the class-based dark variant. Registry components need nothing else. If you use the npm package instead, import minidev-ui-kit/styles.css after Tailwind and add an @source line for the package. See OKLCH colors in Tailwind CSS v4 for the color side.