use-tailwind-v4

name	use-tailwind-v4
description	Tailwind CSS v4 syntax and v3→v4 migration reference. Use when the user mentions 'Tailwind v4', 'upgrade Tailwind', @theme, @utility, or @import 'tailwindcss', or is working in a project whose config indicates v4.

Tailwind CSS v4

v4 Syntax At a Glance

Imports and Setup

/* v4 import (replaces @tailwind directives) */
@import "tailwindcss";

/* Custom utilities (replaces @layer utilities) */
@utility tab-4 {
  tab-size: 4;
}

/* Loading JS config (if still needed) */
@config "../../tailwind.config.js";

CSS Variables for Theme

v4 exposes all theme values as CSS variables. Prefer these over theme():

background-color: var(--color-red-500);
font-family: var(--font-sans);

Quick Reference: v3 → v4 Changes

Renamed Utilities

v3	v4	Notes
shadow-sm	shadow-xs	Scale shifted
shadow	shadow-sm	Scale shifted
drop-shadow-sm	drop-shadow-xs	Scale shifted
drop-shadow	drop-shadow-sm	Scale shifted
blur-sm	blur-xs	Scale shifted
blur	blur-sm	Scale shifted
backdrop-blur-sm	backdrop-blur-xs	Scale shifted
backdrop-blur	backdrop-blur-sm	Scale shifted
rounded-sm	rounded-xs	Scale shifted
rounded	rounded-sm	Scale shifted
outline-none	outline-hidden	outline-none now sets outline-style: none
ring	ring-3	Default changed from 3px to 1px

Deprecated Utilities (Use Opacity Modifiers)

<!-- v3: opacity utilities -->
<div class="bg-black bg-opacity-50">

<!-- v4: opacity modifiers -->
<div class="bg-black/50">

Also: flex-shrink-* → shrink-*, flex-grow-* → grow-*, overflow-ellipsis → text-ellipsis

Default Changes

What	v3 Default	v4 Default
Border color	gray-200	currentColor
Ring width	3px	1px
Ring color	blue-500	currentColor
Button cursor	pointer	default

Variant Stacking Order

Changed from right-to-left to left-to-right:

<!-- v3 -->
<ul class="first:*:pt-0">

<!-- v4 -->
<ul class="*:first:pt-0">

Variable Syntax in Arbitrary Values

<!-- v3: square brackets -->
<div class="bg-[--brand-color]">

<!-- v4: parentheses -->
<div class="bg-(--brand-color)">

Prefix Syntax

<!-- v4 prefixes are at the start, like variants -->
<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">

Upgrading Projects

For project migrations, run the automated upgrade tool:

npx @tailwindcss/upgrade

Requires Node.js 20+. Run in a new branch and review changes.

For complete migration details (PostCSS/Vite/CLI config, custom utilities, framework-specific issues), see references/upgrade-guide.md.