name: tailwindcss-v4
description: Guide for using Tailwind CSS v4 with CSS-first configuration. Use when setting up Tailwind v4, customizing themes, or migrating from v3. Does NOT use tailwind.config.js.

Tailwind CSS v4

This skill provides guidance for using Tailwind CSS v4, which introduces a completely new CSS-first configuration approach.

When to Use This Skill

• Setting up a new project with Tailwind CSS v4
• Customizing theme (colors, spacing, fonts)
• Migrating from Tailwind CSS v3
• Understanding v4-specific syntax and utilities

[!CAUTION]
Do NOT use this skill for Tailwind CSS v3 projects. v4 uses completely different configuration syntax.

Key Differences from v3

1. Import Syntax

/* ❌ v3 (OLD) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ✅ v4 (NEW) */
@import "tailwindcss";

2. Configuration Approach

3. Browser Requirements

v4 requires modern browsers:
- Safari 16.4+
- Chrome 111+
- Firefox 128+

[!WARNING]
If you need to support older browsers, use Tailwind CSS v3.4 instead.

4. Removed/Renamed Utilities

5. Default Changes

• border-* now uses currentColor (was gray-200)
• ring width is now 1px (was 3px)
• Variant stacking: left-to-right (was right-to-left)

Installation

Option 1: Vite (Recommended)

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

/* src/styles.css */
@import "tailwindcss";

Option 2: Next.js

npm install tailwindcss @tailwindcss/postcss postcss

// postcss.config.mjs
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
export default config;

/* app/globals.css */
@import "tailwindcss";

Option 3: PostCSS

npm install tailwindcss @tailwindcss/postcss postcss

// postcss.config.js
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Option 4: CLI

npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch

CSS-first Configuration with @theme

Customize your design system directly in CSS:

@import "tailwindcss";

@theme {
  /* Custom colors using oklch for P3 display support */
  --color-primary: oklch(0.7 0.15 200);
  --color-secondary: oklch(0.6 0.12 280);
  --color-accent: oklch(0.8 0.2 150);

  /* Custom fonts */
  --font-display: "Inter", sans-serif;
  --font-body: "Open Sans", sans-serif;

  /* Custom spacing */
  --spacing-128: 32rem;
  --spacing-144: 36rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom animations */
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

Usage in HTML:

<div class="bg-primary text-secondary font-display">
  <h1 class="animate-fade-in">Hello World</h1>
</div>

Migration from v3

Automated Upgrade (Recommended)

npx @tailwindcss/upgrade

[!NOTE]
Requires Node.js 20+. Run in a new branch and review changes carefully.

Manual Migration Checklist

1. Update dependencies:
   bash npm uninstall tailwindcss postcss-import autoprefixer npm install tailwindcss @tailwindcss/postcss

2. Update PostCSS config:

3. Remove postcss-import and autoprefixer (handled automatically)

4. Replace tailwindcss with @tailwindcss/postcss

5. Update CSS imports:
   css /* Replace @tailwind directives */ @import "tailwindcss";

6. Migrate tailwind.config.js to @theme:
   ```css
   @import "tailwindcss";

@theme {
/ Move your theme.extend values here /
--color-brand: #3b82f6;
}
```

1. Search and replace renamed utilities:
2. shadow-sm → shadow-xs
3. shadow → shadow-sm
4. ring → ring-3
5. outline-none → outline-hidden
6. rounded-sm → rounded-xs

7. rounded → rounded-sm

8. Update opacity utilities:

9. bg-blue-500 bg-opacity-50 → bg-blue-500/50

Decision Tree

What do you need?
├── New project
│   ├── Using Vite → See "Option 1: Vite"
│   ├── Using Next.js → See "Option 2: Next.js"
│   └── Other → See "Option 3: PostCSS" or "Option 4: CLI"
├── Migrate from v3
│   ├── Automated → Run `npx @tailwindcss/upgrade`
│   └── Manual → Follow "Manual Migration Checklist"
└── Customize theme
    └── Use @theme block in CSS

Common Pitfalls

Examples

See complete setup examples:
- Vite Setup - React/Vue with Vite
- Next.js Setup - Next.js App Router
- Custom Theme - Full theme customization

Related Resources

• Official Upgrade Guide
• What's New in v4