home / skills / fusengine / agents / tailwindcss-v4

tailwindcss-v4 skill

safe

/plugins/tailwindcss/skills/tailwindcss-v4

This skill helps you navigate Tailwind CSS v4.1 core features, themes, directives, and migration guides to accelerate styling workflows.

npx playbooks add skill fusengine/agents --skill tailwindcss-v4

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

Files (1)

SKILL.md

3.5 KB

---
name: tailwindcss-v4
description: Tailwind CSS v4.1 core features, @theme, directives, migration guide
user-invocable: false
---

# Tailwind CSS v4.1 Core

## Documentation

- [theme.md](../docs/theme.md) - CSS theme variables, design tokens, customization
- [functions-and-directives.md](../docs/functions-and-directives.md) - @utility, @variant, @theme, @apply
- [adding-custom-styles.md](../docs/adding-custom-styles.md) - Custom utilities and variants
- [detecting-classes-in-source-files.md](../docs/detecting-classes-in-source-files.md) - Content detection
- [upgrade-guide.md](../docs/upgrade-guide.md) - Migration from v3 to v4

## Quick Reference - @theme Namespaces

| Namespace | Generated Utilities |
|-----------|-------------------|
| `--color-*` | bg-*, text-*, border-*, fill-* |
| `--font-*` | font-* |
| `--text-*` | text-xs, text-sm, text-base, etc. |
| `--spacing-*` | p-*, m-*, gap-*, w-*, h-* |
| `--radius-*` | rounded-* |
| `--shadow-*` | shadow-* |
| `--breakpoint-*` | sm:*, md:*, lg:*, xl:* |
| `--animate-*` | animate-spin, animate-bounce, etc. |
| `--ease-*` | ease-in, ease-out, ease-in-out |

## Configuration CSS-first

### Before (v3)
```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#3B82F6' }
    }
  }
}
```

### After (v4)
```css
@import "tailwindcss";

@theme {
  --color-brand: #3B82F6;
}
```

## Directives v4

### @utility - Create a utility
```css
@utility tab-4 {
  tab-size: 4;
}
/* Usage: class="tab-4" */
```

### @variant - Conditional style
```css
.card {
  @variant dark {
    background: #1a1a2e;
  }
}
```

### @custom-variant - New variant
```css
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
/* Usage: dark:bg-gray-900 */
```

## v3 → v4 Breaking Changes

### Removed @tailwind directives

```css
/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";
```

### Renamed utilities

| v3 | v4 |
|----|-----|
| `shadow-sm` | `shadow-xs` |
| `shadow` | `shadow-sm` |
| `rounded-sm` | `rounded-xs` |
| `rounded` | `rounded-sm` |
| `outline-none` | `outline-hidden` |
| `ring` | `ring-3` |

### Removed deprecated utilities

- `bg-opacity-*` → use `bg-black/50`
- `text-opacity-*` → use `text-black/50`
- `flex-shrink-*` → use `shrink-*`
- `flex-grow-*` → use `grow-*`

### Custom utilities syntax

```css
/* v3 */
@layer utilities {
  .tab-4 {
    tab-size: 4;
  }
}

/* v4 */
@utility tab-4 {
  tab-size: 4;
}
```

### Variables in arbitrary values

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

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

### Important modifier position

```html
<!-- v3 -->
<div class="!bg-red-500">

<!-- v4 -->
<div class="bg-red-500!">
```

## Upgrade Tool

```bash
npx @tailwindcss/upgrade
```

Requires Node.js 20+

## Browser Support

- Safari 16.4+
- Chrome 111+
- Firefox 128+

## Installation

```bash
npm install -D tailwindcss @tailwindcss/postcss
# or for Vite
npm install -D @tailwindcss/vite
# or for CLI
npm install -D @tailwindcss/cli
```

## Core API Functions

### --alpha()
Adjust color opacity:
```css
color: --alpha(var(--color-lime-300) / 50%);
```

### --spacing()
Generate spacing values:
```css
margin: --spacing(4);
```

### @apply
Inline utility classes:
```css
.btn {
  @apply px-4 py-2 rounded-lg font-bold;
}
```

## Key Resources

- Official Theme Variables Documentation
- @theme Directive Syntax
- Content Detection Configuration
- Custom Variant Creation
- Animation Keyframes Definition
- CSS Variables Usage

Overview

This skill documents Tailwind CSS v4.1 core features, the new @theme system, directives, and a focused migration guide from v3 to v4. It concentrates on the CSS-first configuration, updated utility/variant syntax, and the new naming and variable behaviors you need to adopt. The content highlights installation, browser support, and key API functions for day-to-day development.

How this skill works

The skill inspects and explains v4’s CSS-first approach where design tokens live in @theme CSS variables that generate utilities automatically. It describes directive changes (@import "tailwindcss" replacing @tailwind layers), new directives like @utility, @variant, and @custom-variant, and how arbitrary values and important modifiers are now parsed. It also covers migration steps, renamed utilities, removed deprecated utilities, and the upgrade CLI tool requirements.

When to use it

When migrating a project from Tailwind v3 to v4 and you need a clear change list and examples.
When adopting CSS-first theming with centralized design tokens expressed as @theme variables.
When creating custom utilities, custom variants, or new conditional styles using @utility and @variant.
When configuring content detection and custom style layers in a v4 workflow.
When you need quick reference for renamed utilities, removed features, and browser support.

Best practices

Define global design tokens in a single @theme block to generate consistent utilities.
Replace v3 @tailwind layers with @import "tailwindcss" and move custom utilities to @utility blocks.
Prefer new variable syntax bg-(--brand-color) for arbitrary values and move important modifiers to the end (e.g., bg-red-500!).
Use @custom-variant to create theme-aware selectors that scope styles to data-theme attributes.
Run the upgrade tool (Node.js 20+) and manually verify renamed utilities and removed features in your UI.

Example use cases

Convert an existing v3 project: run the upgrade tool, replace @tailwind directives, and map renamed utilities.
Create a design system: store colors, spacing, radii, and shadows in @theme to auto-generate utility classes.
Add a custom utility: define tab-size via @utility tab-4 and use it directly as class="tab-4".
Implement dark mode variants: register a @custom-variant that targets [data-theme="dark"] and use dark:bg-* classes.
Compose component styles: use @apply with generated utilities to keep component rules concise.

FAQ

How do I convert v3 @layer utilities to v4?

Move custom utilities into @utility blocks and import Tailwind with @import "tailwindcss" instead of @tailwind base/components/utilities.

Where do design tokens live in v4?

Design tokens are defined as CSS variables inside an @theme block (for example --color-brand) and generate corresponding utility classes.