Tailwind CSS v4 Skill | Agent Skills

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.

Agent Skills: Tailwind CSS v4

Install this agent skill to your local

Skill Files