---

name: tailwindcss-v4 description: "Tailwind CSS v4 patterns: CSS-first config, @theme/@utility/@variant directives, migration from v3. Use when working with Tailwind v4 projects." proactive: match match:

• "tailwind"
• "tailwindcss"
• "@theme"
• "@utility"
• "@variant"

---

Tailwind CSS v4 Skill

CSS-first configuration, new directives, migration from v3.

Quick Reference

v4 Entry Point

@import "tailwindcss";

NOT the v3 way:

/* ❌ These cause errors in v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

Key Directives

| Directive | Purpose | |-----------|---------| | @theme | Define design tokens (colors, spacing, fonts) | | @utility | Create custom utility classes | | @variant | Define custom variants (hover, focus, etc.) | | @source | Control class detection and safelisting | | @reference | Import for @apply without emitting CSS |

Theme Configuration (CSS-first)

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-display: "Inter", sans-serif;
  --spacing-18: 4.5rem;
}

NOT tailwind.config.js:

// ❌ v3 pattern - don't use in v4
module.exports = {
  theme: {
    extend: {
      colors: { primary: '#3b82f6' }
    }
  }
}

Custom Utilities

@utility content-auto {
  content-visibility: auto;
}

/* Functional utility must end in -* */
@utility tab-* {
  --tab-size: --value(--spacing-*, [integer]);
  tab-size: var(--tab-size);
}

Custom Variants

Use @custom-variant to define new variants (not @variant).

@custom-variant hocus (&:hover, &:focus);

/* Dark mode with class strategy */
@custom-variant dark (&:is(.dark *));

/* Body block with @slot */
@custom-variant hocus {
  &:hover, &:focus { @slot; }
}

Theme Configuration

@theme {
  --color-primary: #3b82f6;

  /* Clear namespace */
  --color-*: initial;
}

Theme Flags

• default: Merge with default theme
• inline: Emit variables to output
• static: Use values but don't emit vars
• reference: Use values but don't emit CSS

@theme inline {
  --font-sans: "SF Pro Text", system-ui;
}

New Gradient Syntax

<!-- v4 preferred - supports interpolation color space -->
<div class="bg-linear-to-r/oklch from-blue-500 to-purple-500"></div>

<!-- Also: bg-linear-to-b, bg-radial, bg-conic -->

New Variants

• @min-[400px]: / @max-[600px]: (Container queries)
• starting: (@starting-style)
• details-content: (::details-content)
• inverted-colors:, noscript:, print:

Safelisting Classes

/* Inline safelist */
@source inline("bg-red-500 text-white hidden");

/* From external source */
@source "../content/**/*.md";

Migration from v3

| v3 | v4 | |----|-----| | @tailwind base/components/utilities | @import "tailwindcss" | | tailwind.config.js theme.extend | @theme { --color-* } | | PostCSS tailwindcss plugin | @tailwindcss/postcss | | @apply with config values | @reference import first |

PostCSS Setup

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {}  // NOT 'tailwindcss'
  }
}

Vite Setup

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()]
}

Sources: Tailwind v4 Docs, GitHub