Tailwind CSS v4+ Patterns

Quick Guide: Tailwind CSS v4 uses CSS-first configuration with @import "tailwindcss" and @theme directive (NOT tailwind.config.js). Define design tokens as CSS variables in @theme, create custom utilities with @utility, custom variants with @custom-variant. Automatic content detection (no content array). Use @tailwindcss/vite for Vite, @tailwindcss/webpack for Webpack. All colors use oklch. v4.1 adds text shadows, masks, and input-device variants. No Sass/Less/Stylus support.

Detailed Resources:

• For code examples, see examples/ folder:
  • core.md - Setup, source detection, responsive design, dark mode, state variants, theme customization
  • advanced.md - Custom utilities, custom variants, container queries, 3D transforms, text shadows, masks, input-device targeting, animations, component extraction

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use @import "tailwindcss" and @theme for configuration - NEVER use tailwind.config.js, @tailwind base, or module.exports)

(You MUST use @utility for custom utilities - NEVER use @layer utilities {} (v3 syntax))

(You MUST use oklch or CSS variable references for custom colors in @theme - NEVER use hex/rgb for theme tokens)

(You MUST use @tailwindcss/vite for Vite, @tailwindcss/webpack for Webpack, @tailwindcss/postcss for others - NEVER use tailwindcss directly as PostCSS plugin)

(You MUST specify border colors explicitly - v4 defaults to currentColor not gray-200)

</critical_requirements>

Auto-detection: Tailwind CSS, tailwindcss, @import "tailwindcss", @theme, @utility, @custom-variant, utility classes, bg-, text-, flex, grid, responsive design, dark:, hover:, focus:, @tailwindcss/vite, @tailwindcss/postcss, @tailwindcss/webpack, tailwind-merge, cn()

When to use:

• Styling with utility-first CSS classes directly in markup
• Configuring design tokens with CSS-first @theme directive
• Implementing responsive design with breakpoint variants
• Adding dark mode with dark: variant
• Creating custom utilities and variants in CSS
• Building component libraries with Tailwind utility classes
• Using container queries, 3D transforms, or modern CSS features

Key patterns covered:

• CSS-first setup with @import "tailwindcss" and @theme
• Responsive design with breakpoint variants (sm:, md:, lg:)
• Dark mode configuration (media, class, data-attribute strategies)
• State variants (hover:, focus:, group-*:, peer-*:)
• Theme customization with @theme namespaces
• Custom utilities with @utility and functional values
• Custom variants with @custom-variant
• Container queries (@container, @sm:, @max-*:)
• 3D transforms (rotate-x-*, perspective-*, transform-3d)
• Animation with @starting-style and @keyframes
• Text shadows, masks, overflow-wrap (v4.1)
• Component extraction with cn() (clsx + tailwind-merge)
• Migration notes from v3 to v4

When NOT to use:

• Projects requiring Sass/Less/Stylus (v4 is a standalone preprocessor, no Sass support)
• Projects needing IE11 or older browser support (requires Safari 16.4+, Chrome 111+, Firefox 128+)
• Tiny projects where a full utility framework is overkill (use plain CSS)
• Projects already using an established CSS Modules or CSS-in-JS design system

Philosophy

Tailwind CSS v4 follows a utility-first, CSS-native approach: style directly in markup using composable utility classes, configure design tokens in CSS with @theme, and extend with @utility/@custom-variant directives. No JavaScript configuration files needed.

Core Principles:

• Utility-first: Compose styles from small, single-purpose classes in HTML
• CSS-first configuration: Design tokens defined in CSS via @theme, not JavaScript
• Zero configuration defaults: Automatic content detection, sensible default theme
• Variant-driven states: Responsive, dark mode, hover, focus -- all via class prefixes
• Modern CSS foundation: Built on cascade layers, @property, color-mix(), oklch colors
• Performance-first: 5x faster full builds, 100x faster incremental rebuilds vs v3

v4 vs v3 -- Key Differences:

Core Patterns

Pattern 1: CSS-First Setup and Configuration

Tailwind v4 replaces JavaScript config with CSS-first configuration. Use @import "tailwindcss" instead of @tailwind directives, and @theme instead of tailwind.config.js.

Installation Options

Vite projects (recommended): Use @tailwindcss/vite for optimal performance. Webpack projects: Use @tailwindcss/webpack (added in v4.2). Other bundlers: Use @tailwindcss/postcss as PostCSS plugin. CLI: Use @tailwindcss/cli for standalone builds.

Key Concepts

• @import "tailwindcss" replaces the three @tailwind directives
• @theme defines design tokens that generate utility classes AND CSS variables
• @source adds paths not caught by automatic content detection
• @source not excludes paths from scanning (v4.1)
• @source inline("...") safelists specific utilities without source files (v4.1)
• @reference imports theme/utilities for scoped styles (Vue SFC, CSS Modules) without duplicating output
• No content array needed -- Tailwind auto-detects template files respecting .gitignore

For implementation examples, see examples/core.md.

Pattern 2: Responsive Design with Breakpoint Variants

Tailwind v4 uses mobile-first responsive design with breakpoint variants. Default breakpoints: sm (40rem), md (48rem), lg (64rem), xl (80rem), 2xl (96rem).

Key Concepts

• Mobile-first: base styles apply to all, breakpoint variants add overrides
• Custom breakpoints defined in @theme with --breakpoint-* namespace
• Stack breakpoints for ranges: md:max-lg:hidden (hide between md and lg)
• Use max-* variants for max-width queries: max-md:hidden

For implementation examples, see examples/core.md.

Pattern 3: Dark Mode

Tailwind v4 supports three dark mode strategies: media query (default), class-based toggle, and data-attribute toggle. Override the dark variant with `@custom-varia