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