home / skills / nweii / agent-stuff / use-tailwind-v4

use-tailwind-v4 skill

safe

This skill helps you migrate Tailwind CSS projects to v4 by summarizing syntax changes, defaults, and upgrade steps for smooth adoption.

npx playbooks add skill nweii/agent-stuff --skill use-tailwind-v4

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.8 KB

---
name: use-tailwind-v4
description: "Tailwind CSS v4 reference and migration guide. Use for v4 projects, syntax changes, upgrading from v3, and troubleshooting v4-specific utility patterns or configuration differences."
---

# Tailwind CSS v4

## v4 Syntax At a Glance

### Imports and Setup

```css
/* 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()`:

```css
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)

```html
<!-- 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:

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

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

### Variable Syntax in Arbitrary Values

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

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

### Prefix Syntax

```html
<!-- 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:

```bash
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](references/upgrade-guide.md).

Overview

This skill provides a focused Tailwind CSS v4 reference and migration guide for developers upgrading from v3 or starting new v4 projects. It highlights syntax changes, renamed utilities, new defaults, and practical migration commands. Use it to resolve v4-specific configuration and utility differences quickly.

How this skill works

The skill inspects common v3 → v4 changes and explains the updated syntax, variable usage, and variant stacking rules. It summarizes renamed and deprecated utilities, new defaults, and the preferred patterns (CSS variables, new arbitrary value syntax, prefix placement). It also points to the automated upgrade tool and upgrade workflow recommendations.

When to use it

Migrating an existing Tailwind v3 project to v4 and auditing breaking changes.
Starting a new project built on Tailwind CSS v4 and needing current syntax guidance.
Troubleshooting utility or configuration behavior that changed between v3 and v4.
Updating build/config tools (PostCSS, Vite, CLI) to align with v4 requirements.
Refactoring custom utilities or theme values to the v4 CSS-variable model.

Best practices

Prefer the v4-exposed CSS variables (e.g., var(--color-red-500)) over theme() calls for runtime theming.
Run the automated upgrade tool (npx @tailwindcss/upgrade) in a feature branch and review diffs carefully.
Replace deprecated opacity utilities with slash modifiers (bg-black/50) and rename shifted utilities per the quick reference.
Use the new parentheses syntax for arbitrary values (bg-(--brand-color)) and place any project prefix at the start of class lists (tw:).
Re-check variant stacking in places that used right-to-left stacking; update to left-to-right order where needed.

Example use cases

Convert project-wide shadows and blur utilities after v4 renames (e.g., shadow → shadow-sm, shadow-sm → shadow-xs).
Migrate theme tokens to CSS variables to enable runtime color and font swapping.
Fix UI differences after default changes such as ring width/color or border-color fallbacks.
Adjust complex variant expressions to the new left-to-right stacking order.
Audit and update custom utilities to the v4 @utility and @config setup when replacing legacy @tailwind/@layer usage.

FAQ

Do I need Node.js 20 to upgrade?

Yes; the automated upgrade tool requires Node.js 20 or newer. Run it in a separate branch and review changes.

How do I convert opacity utilities?

Replace bg-opacity-50 style utilities with the slash modifier form, for example bg-black/50.

Where are theme values in v4?

Theme values are exposed as CSS variables (var(--color-...), var(--font-sans)), which are the recommended access pattern.