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:

| Aspect | v3 | v4 | | ------------------ | ------------------------------------- | ----------------------- | | Config | tailwind.config.js | @theme in CSS | | Import | @tailwind base/components/utilities | @import "tailwindcss" | | Custom utilities | @layer utilities {} | @utility name {} | | Custom variants | addVariant() plugin | @custom-variant | | Content detection | Manual content: [] | Automatic | | Colors | sRGB hex/rgb | oklch (P3 gamut) | | Border default | gray-200 | currentColor | | Ring default | 3px blue-500 | 1px currentColor | | Important modifier | !flex | flex! | | Arbitrary vars | bg-[--var] | bg-(--var) | | Container queries | Plugin required | Built-in | | 3D transforms | Not available | Built-in | | Text shadows | Not available | Built-in (v4.1) | | Masks | Not available | Built-in (v4.1) |

</philosophy>

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-variant.

Strategies

Media query (default): Uses prefers-color-scheme: dark -- zero config
Class-based: Add .dark class to <html> -- use @custom-variant dark
Data-attribute: Use data-theme="dark" -- use @custom-variant dark

Key Concepts

Default dark mode works with system preference, no config needed
For manual toggle, override the dark variant with @custom-variant
Use (&:where(.dark, .dark *)) selector for class strategy
Theme variables in @theme can reference CSS variables set by theme class

For implementation examples, see examples/core.md.

Pattern 4: State Variants

Tailwind v4 provides comprehensive state variants for interactive styling. The not-* variant is new in v4.

Available Variants

Pseudo-classes: hover:, focus:, active:, visited:, first:, last:, odd:, even:, disabled:, required:, invalid:
Group/Peer: group-hover:, group-focus:, peer-checked:, peer-invalid:
Data attributes: data-[state=active]:, data-current:
New in v4.0: not-hover:, not-focus:, inert:, starting: (for @starting-style)
New in v4.1: pointer-fine:, pointer-coarse:, user-valid:, user-invalid:, noscript:, details-content:, inverted-colors:
Container queries: @sm:, @md:, @lg:, @max-sm:

Key v4 Changes

hover: only applies on devices with hover capability (no more mobile ghost hovers)
not-* variant styles when condition is NOT met
Variant stacking is left-to-right (CSS order): dark:hover:bg-gray-700

For implementation examples, see examples/core.md.

Pattern 5: Theme Customization with @theme

The @theme directive defines design tokens that generate both utility classes and CSS variables. Each namespace maps to specific utility types.

Namespaces

| Namespace | Generates | ------------------ | --color-* | --font-* | --font-weight-* | --text-* | --tracking-* | --leading-* | --spacing-* | --breakpoint-* | --container-* | --radius-* | --shadow-* | --inset-shadow-* | --drop-shadow-* | --ease-* | --animate-* | --blur-* | --perspective-* | --aspect-* | Example | | ------------------------ | -------------------------------- | | Color utilities | bg-brand-500, text-brand-500 | | Font family | font-display | | Font weight | font-bold | | Font size | text-display | | Letter spacing | tracking-wide | | Line height | leading-tight | | Spacing and sizing | px-compact, max-h-16 | | Responsive variants | 3xl:flex | | Container query variants | @sm:*, max-w-md | | Border radius | rounded-card | | Box shadows | shadow-card | | Inset box shadows | inset-shadow-xs | | Drop shadow filters | drop-shadow-md | | Timing functions | ease-fluid | | Animations | animate-fade-in | | Blur filters | blur-card | | 3D perspective | perspective-card | | Aspect ratios | aspect-cinema |

Key Concepts

--color-*: initial resets all default colors before defining custom ones
--*: initial resets the entire default theme
@theme inline prevents CSS variable resolution issues when referencing other variables
@theme static generates CSS variables even when utilities are unused
@keyframes can be defined inside @theme for animation tokens

For implementation examples, see examples/core.md.

Pattern 6: Custom Utilities with @utility

The @utility directive replaces v3's @layer utilities {}. Supports static utilities, functional utilities with --value(), and modifiers with --modifier().

Types of Custom Utilities

Static: Fixed CSS declarations (@utility content-auto { content-visibility: auto; })
Functional: Accept values via --value() (@utility tab-* { tab-size: --value(integer); })
With modifiers: Optional modifiers via --modifier() for secondary values

Value Resolution

--value(--namespace-*) matches theme variables
--value(integer) matches bare integer values
--value([length]) matches arbitrary values in brackets
Multiple --value() declarations cascade (last match wins)

For implementation examples, see examples/advanced.md.

Pattern 7: Custom Variants with @custom-variant

The @custom-variant directive replaces v3's addVariant() plugin API. Define conditional styling rules in CSS. The @variant directive applies existing variants inline within CSS rules.

Syntax Forms

@custom-variant shorthand: @custom-variant name (selector);
@custom-variant block: @custom-variant name { /* rules with @slot */ }
@variant (inline): @variant dark { /* styles */ } -- apply a variant inside custom CSS

For implementation examples, see examples/advanced.md.

Pattern 8: Container Queries

Container queries are built into v4 core (no plugin needed). Style elements based on container size, not viewport.

Key Concepts

@container makes an element a query container
@sm:, @md:, @lg: apply at container breakpoints (not viewport)
@max-sm:, @max-md: for max-width container queries
@min-md:@max-xl: for range queries
Named containers with @container/name and @sm/name:

For implementation examples, see examples/advanced.md.

Pattern 9: 3D Transforms and Modern CSS

Tailwind v4 adds first-class 3D transform utilities and leverages modern CSS features.

3D Transform Utilities

rotate-x-*, rotate-y-*, rotate-z-* for 3D rotation
translate-z-* for depth translation
scale-z-* for depth scaling
perspective-* and perspective-origin-* for 3D perspective
transform-3d to enable 3D transform context
backface-hidden / backface-visible for card-flip effects

Other Modern Features

@starting-style via starting: variant for enter/exit animations
field-sizing-content for auto-resizing textareas
color-scheme-dark for native dark mode scrollbars
inset-shadow-* and inset-ring-* for layered box shadows
text-shadow-* for text shadows with color/opacity support (v4.1)
mask-* for gradient and image masking (v4.1)
wrap-break-word / wrap-anywhere for overflow-wrap control (v4.1)
--alpha() function for adjusting color opacity in custom CSS

For implementation examples, see examples/advanced.md.

Pattern 10: Component Class Composition with cn()

Use cn() (clsx + tailwind-merge) to handle class composition and conflict resolution. Compose utility classes programmatically when components need variants or overridable styles.

Key Concepts

cn() combines clsx (conditional classes) with twMerge (conflict resolution)
External className should always be last in cn() to allow consumer overrides
Use variant objects for multi-variant components, cn() for simple composition
Prefer cn() over @apply for component extraction (keeps utilities visible in code)

For implementation examples, see examples/advanced.md.

</patterns>

<decision_framework>

Decision Framework

When to Use Which Styling Approach

Need component variants (size, intent, state)?
|-- YES --> Variant objects + cn() + Tailwind classes
|-- NO --> Just utility classes in markup

Need custom utility not in Tailwind?
|-- YES --> Is it a single fixed style?
|   |-- YES --> @utility name { declarations }
|   |-- NO --> @utility name-* { --value() }
|-- NO --> Use built-in utilities

Need conditional styling based on parent/sibling state?
|-- YES --> Is parent state?
|   |-- YES --> group/group-* pattern
|   |-- NO --> peer/peer-* pattern
|-- NO --> Direct state variants (hover:, focus:)

Need responsive behavior based on...?
|-- Viewport size --> sm:/md:/lg: breakpoint variants
|-- Container size --> @container + @sm:/@md: variants
|-- Neither --> Static styling

Dark Mode Strategy

Is dark mode automatic (system preference only)?
|-- YES --> No config needed (default prefers-color-scheme)
|-- NO --> Need manual toggle?
    |-- YES --> Using class on <html>?
    |   |-- YES --> @custom-variant dark (&:where(.dark, .dark *))
    |   |-- NO --> @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *))
    |-- NO --> Default media query

Theme Customization Scope

Need to add a few custom tokens?
|-- YES --> Add to @theme alongside defaults

Need to replace an entire namespace?
|-- YES --> --namespace-*: initial; then define custom tokens

Need fully custom theme (no defaults)?
|-- YES --> --*: initial; then define everything

Need to share theme across projects?
|-- YES --> Create shared theme.css, import with @import

v3 to v4 Migration Decision

Is the project actively maintained?
|-- YES --> Does it use tailwind.config.js plugins?
|   |-- YES --> Can plugins be replaced with @utility/@custom-variant?
|   |   |-- YES --> Migrate to v4
|   |   |-- NO --> Keep v3 or use @config/@plugin compatibility
|   |-- NO --> Migrate to v4 (run npx @tailwindcss/upgrade)
|-- NO --> Stay on v3.4 (stable, still supported)

</decision_framework>

Integration Notes

Bundler Setup:

Use @tailwindcss/vite for Vite-based projects (fastest)
Use @tailwindcss/webpack for Webpack projects (v4.2+)
Use @tailwindcss/postcss for other bundlers
Use @tailwindcss/cli for standalone builds
autoprefixer and postcss-import are NOT needed with v4

Component Integration:

Use cn() for class composition and conflict resolution
Forward className prop for consumer overrides
Use tailwind-merge to resolve conflicting utility classes

What Tailwind Does NOT Replace:

Complex CSS animations / @keyframes (use @theme for tokens, custom CSS for complex sequences)
CSS variables for runtime values (use bg-(--my-var) arbitrary syntax)

</integration>

<red_flags>

RED FLAGS

High Priority Issues:

Using tailwind.config.js without @config directive (v4 does NOT auto-detect JS config)
Using @tailwind base; @tailwind components; @tailwind utilities; (v3 syntax, use @import "tailwindcss")
Using @layer utilities {} for custom utilities (use @utility directive)
Using tailwindcss directly as PostCSS plugin (use @tailwindcss/postcss)
Using !flex important syntax (v4 uses flex! -- trailing not leading)
Using bg-[--my-var] for CSS variables (v4 uses bg-(--my-var) with parentheses)
Using hex/rgb colors in @theme (use oklch for P3 gamut support)
Assuming border defaults to gray-200 (v4 defaults to currentColor)
Assuming ring defaults to 3px (v4 defaults to 1px)

Medium Priority Issues:

Using @apply for component extraction (use cn() with tailwind-merge instead -- keeps utilities visible)
Not specifying @source for node_modules UI libraries (automatic detection skips node_modules)
Using Sass/Less/Stylus with Tailwind v4 (not supported -- v4 is a standalone preprocessor)
Using autoprefixer or postcss-import (not needed with v4)
Using transform-none to reset transforms (v4 uses individual properties, use scale-none / rotate-0)

Common Mistakes:

Forgetting @custom-variant dark when using class-based dark mode toggle
Using content: ['./src/**/*.tsx'] (v4 auto-detects, no content array)
Mixing v3 and v4 syntax in the same project
Not running npx @tailwindcss/upgrade for automated migration

Gotchas and Edge Cases:

Variant stacking order changed: v3 was right-to-left, v4 is left-to-right (follows CSS cascade)
hover: only triggers on devices with hover capability (no phantom hover on touch devices)
space-y-* / divide-* changed selectors: v3 used :not([hidden]) ~ :not([hidden]), v4 uses :not(:last-child) -- prefer gap-* with flex/grid
Grid template values use underscores for spaces: grid-cols-[max-content_auto] (not commas)
shadow-sm in v3 = shadow-xs in v4, shadow in v3 = shadow-sm in v4 (whole scale shifted)
rounded-sm in v3 = rounded-xs in v4, rounded in v3 = rounded-sm in v4
outline-none in v3 = outline-hidden in v4 (accessibility improvement)
ring in v3 (3px) = ring-3 in v4 (default is now 1px)
Browser requirements: Safari 16.4+, Chrome 111+, Firefox 128+ (no IE11, no older browsers)

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

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)

Failure to follow these rules will produce v3 code that does not work with Tailwind CSS v4.

</critical_reminders>

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>

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

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:

</philosophy>

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

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-variant.

Strategies

Media query (default): Uses prefers-color-scheme: dark -- zero config
Class-based: Add .dark class to <html> -- use @custom-variant dark
Data-attribute: Use data-theme="dark" -- use @custom-variant dark

Key Concepts

Default dark mode works with system preference, no config needed
For manual toggle, override the dark variant with @custom-variant
Use (&:where(.dark, .dark *)) selector for class strategy
Theme variables in @theme can reference CSS variables set by theme class

For implementation examples, see examples/core.md.

Pattern 4: State Variants

Tailwind v4 provides comprehensive state variants for interactive styling. The not-* variant is new in v4.

Available Variants

Pseudo-classes: hover:, focus:, active:, visited:, first:, last:, odd:, even:, disabled:, required:, invalid:
Group/Peer: group-hover:, group-focus:, peer-checked:, peer-invalid:
Data attributes: data-[state=active]:, data-current:
New in v4.0: not-hover:, not-focus:, inert:, starting: (for @starting-style)
New in v4.1: pointer-fine:, pointer-coarse:, user-valid:, user-invalid:, noscript:, details-content:, inverted-colors:
Container queries: @sm:, @md:, @lg:, @max-sm:

Key v4 Changes

hover: only applies on devices with hover capability (no more mobile ghost hovers)
not-* variant styles when condition is NOT met
Variant stacking is left-to-right (CSS order): dark:hover:bg-gray-700

For implementation examples, see examples/core.md.

Pattern 5: Theme Customization with @theme

The @theme directive defines design tokens that generate both utility classes and CSS variables. Each namespace maps to specific utility types.

Namespaces

| Namespace | Generates | Example | | ------------------ | ------------------------ | -------------------------------- | | --color-* | Color utilities | bg-brand-500, text-brand-500 | | --font-* | Font family | font-display | | --font-weight-* | Font weight | font-bold | | --text-* | Font size | text-display | | --tracking-* | Letter spacing | tracking-wide | | --leading-* | Line height | leading-tight | | --spacing-* | Spacing and sizing | px-compact, max-h-16 | | --breakpoint-* | Responsive variants | 3xl:flex | | --container-* | Container query variants | @sm:*, max-w-md | | --radius-* | Border radius | rounded-card | | --shadow-* | Box shadows | shadow-card | | --inset-shadow-* | Inset box shadows | inset-shadow-xs | | --drop-shadow-* | Drop shadow filters | drop-shadow-md | | --ease-* | Timing functions | ease-fluid | | --animate-* | Animations | animate-fade-in | | --blur-* | Blur filters | blur-card | | --perspective-* | 3D perspective | perspective-card | | --aspect-* | Aspect ratios | aspect-cinema |

Key Concepts

--color-*: initial resets all default colors before defining custom ones
--*: initial resets the entire default theme
@theme inline prevents CSS variable resolution issues when referencing other variables
@theme static generates CSS variables even when utilities are unused
@keyframes can be defined inside @theme for animation tokens

For implementation examples, see examples/core.md.

Pattern 6: Custom Utilities with @utility

The @utility directive replaces v3's @layer utilities {}. Supports static utilities, functional utilities with --value(), and modifiers with --modifier().

Types of Custom Utilities

Static: Fixed CSS declarations (@utility content-auto { content-visibility: auto; })
Functional: Accept values via --value() (@utility tab-* { tab-size: --value(integer); })
With modifiers: Optional modifiers via --modifier() for secondary values

Value Resolution

--value(--namespace-*) matches theme variables
--value(integer) matches bare integer values
--value([length]) matches arbitrary values in brackets
Multiple --value() declarations cascade (last match wins)

For implementation examples, see examples/advanced.md.

Pattern 7: Custom Variants with @custom-variant

The @custom-variant directive replaces v3's addVariant() plugin API. Define conditional styling rules in CSS. The @variant directive applies existing variants inline within CSS rules.

Syntax Forms

@custom-variant shorthand: @custom-variant name (selector);
@custom-variant block: @custom-variant name { /* rules with @slot */ }
@variant (inline): @variant dark { /* styles */ } -- apply a variant inside custom CSS

For implementation examples, see examples/advanced.md.

Pattern 8: Container Queries

Container queries are built into v4 core (no plugin needed). Style elements based on container size, not viewport.

Key Concepts

@container makes an element a query container
@sm:, @md:, @lg: apply at container breakpoints (not viewport)
@max-sm:, @max-md: for max-width container queries
@min-md:@max-xl: for range queries
Named containers with @container/name and @sm/name:

For implementation examples, see examples/advanced.md.

Pattern 9: 3D Transforms and Modern CSS

Tailwind v4 adds first-class 3D transform utilities and leverages modern CSS features.

3D Transform Utilities

rotate-x-*, rotate-y-*, rotate-z-* for 3D rotation
translate-z-* for depth translation
scale-z-* for depth scaling
perspective-* and perspective-origin-* for 3D perspective
transform-3d to enable 3D transform context
backface-hidden / backface-visible for card-flip effects

Other Modern Features

@starting-style via starting: variant for enter/exit animations
field-sizing-content for auto-resizing textareas
color-scheme-dark for native dark mode scrollbars
inset-shadow-* and inset-ring-* for layered box shadows
text-shadow-* for text shadows with color/opacity support (v4.1)
mask-* for gradient and image masking (v4.1)
wrap-break-word / wrap-anywhere for overflow-wrap control (v4.1)
--alpha() function for adjusting color opacity in custom CSS

For implementation examples, see examples/advanced.md.

Pattern 10: Component Class Composition with cn()

Use cn() (clsx + tailwind-merge) to handle class composition and conflict resolution. Compose utility classes programmatically when components need variants or overridable styles.

Key Concepts

cn() combines clsx (conditional classes) with twMerge (conflict resolution)
External className should always be last in cn() to allow consumer overrides
Use variant objects for multi-variant components, cn() for simple composition
Prefer cn() over @apply for component extraction (keeps utilities visible in code)

For implementation examples, see examples/advanced.md.

</patterns>

<decision_framework>

Decision Framework

When to Use Which Styling Approach

Need component variants (size, intent, state)?
|-- YES --> Variant objects + cn() + Tailwind classes
|-- NO --> Just utility classes in markup

Need custom utility not in Tailwind?
|-- YES --> Is it a single fixed style?
|   |-- YES --> @utility name { declarations }
|   |-- NO --> @utility name-* { --value() }
|-- NO --> Use built-in utilities

Need conditional styling based on parent/sibling state?
|-- YES --> Is parent state?
|   |-- YES --> group/group-* pattern
|   |-- NO --> peer/peer-* pattern
|-- NO --> Direct state variants (hover:, focus:)

Need responsive behavior based on...?
|-- Viewport size --> sm:/md:/lg: breakpoint variants
|-- Container size --> @container + @sm:/@md: variants
|-- Neither --> Static styling

Dark Mode Strategy

Is dark mode automatic (system preference only)?
|-- YES --> No config needed (default prefers-color-scheme)
|-- NO --> Need manual toggle?
    |-- YES --> Using class on <html>?
    |   |-- YES --> @custom-variant dark (&:where(.dark, .dark *))
    |   |-- NO --> @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *))
    |-- NO --> Default media query

Theme Customization Scope

Need to add a few custom tokens?
|-- YES --> Add to @theme alongside defaults

Need to replace an entire namespace?
|-- YES --> --namespace-*: initial; then define custom tokens

Need fully custom theme (no defaults)?
|-- YES --> --*: initial; then define everything

Need to share theme across projects?
|-- YES --> Create shared theme.css, import with @import

v3 to v4 Migration Decision

Is the project actively maintained?
|-- YES --> Does it use tailwind.config.js plugins?
|   |-- YES --> Can plugins be replaced with @utility/@custom-variant?
|   |   |-- YES --> Migrate to v4
|   |   |-- NO --> Keep v3 or use @config/@plugin compatibility
|   |-- NO --> Migrate to v4 (run npx @tailwindcss/upgrade)
|-- NO --> Stay on v3.4 (stable, still supported)

</decision_framework>

Integration Notes

Bundler Setup:

Use @tailwindcss/vite for Vite-based projects (fastest)
Use @tailwindcss/webpack for Webpack projects (v4.2+)
Use @tailwindcss/postcss for other bundlers
Use @tailwindcss/cli for standalone builds
autoprefixer and postcss-import are NOT needed with v4

Component Integration:

Use cn() for class composition and conflict resolution
Forward className prop for consumer overrides
Use tailwind-merge to resolve conflicting utility classes

What Tailwind Does NOT Replace:

Complex CSS animations / @keyframes (use @theme for tokens, custom CSS for complex sequences)
CSS variables for runtime values (use bg-(--my-var) arbitrary syntax)

</integration>

<red_flags>

RED FLAGS

High Priority Issues:

Using tailwind.config.js without @config directive (v4 does NOT auto-detect JS config)
Using @tailwind base; @tailwind components; @tailwind utilities; (v3 syntax, use @import "tailwindcss")
Using @layer utilities {} for custom utilities (use @utility directive)
Using tailwindcss directly as PostCSS plugin (use @tailwindcss/postcss)
Using !flex important syntax (v4 uses flex! -- trailing not leading)
Using bg-[--my-var] for CSS variables (v4 uses bg-(--my-var) with parentheses)
Using hex/rgb colors in @theme (use oklch for P3 gamut support)
Assuming border defaults to gray-200 (v4 defaults to currentColor)
Assuming ring defaults to 3px (v4 defaults to 1px)

Medium Priority Issues:

Using @apply for component extraction (use cn() with tailwind-merge instead -- keeps utilities visible)
Not specifying @source for node_modules UI libraries (automatic detection skips node_modules)
Using Sass/Less/Stylus with Tailwind v4 (not supported -- v4 is a standalone preprocessor)
Using autoprefixer or postcss-import (not needed with v4)
Using transform-none to reset transforms (v4 uses individual properties, use scale-none / rotate-0)

Common Mistakes:

Forgetting @custom-variant dark when using class-based dark mode toggle
Using content: ['./src/**/*.tsx'] (v4 auto-detects, no content array)
Mixing v3 and v4 syntax in the same project
Not running npx @tailwindcss/upgrade for automated migration

Gotchas and Edge Cases:

Variant stacking order changed: v3 was right-to-left, v4 is left-to-right (follows CSS cascade)
hover: only triggers on devices with hover capability (no phantom hover on touch devices)
space-y-* / divide-* changed selectors: v3 used :not([hidden]) ~ :not([hidden]), v4 uses :not(:last-child) -- prefer gap-* with flex/grid
Grid template values use underscores for spaces: grid-cols-[max-content_auto] (not commas)
shadow-sm in v3 = shadow-xs in v4, shadow in v3 = shadow-sm in v4 (whole scale shifted)
rounded-sm in v3 = rounded-xs in v4, rounded in v3 = rounded-sm in v4
outline-none in v3 = outline-hidden in v4 (accessibility improvement)
ring in v3 (3px) = ring-3 in v4 (default is now 1px)
Browser requirements: Safari 16.4+, Chrome 111+, Firefox 128+ (no IE11, no older browsers)

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

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)

Failure to follow these rules will produce v3 code that does not work with Tailwind CSS v4.

</critical_reminders>

Adoption

agents-inc/web-styling-tailwind

$ install --global

Security Scan Results

SKILL.md

Tailwind CSS v4+ Patterns

CRITICAL: Before Using This Skill

Philosophy

Core Patterns

Pattern 1: CSS-First Setup and Configuration

Installation Options

Key Concepts

Pattern 2: Responsive Design with Breakpoint Variants

Key Concepts

Pattern 3: Dark Mode

Strategies

Key Concepts

Pattern 4: State Variants

Available Variants

Key v4 Changes

Pattern 5: Theme Customization with @theme

Namespaces

Key Concepts

Pattern 6: Custom Utilities with @utility

Types of Custom Utilities

Value Resolution

Pattern 7: Custom Variants with @custom-variant

Syntax Forms

Pattern 8: Container Queries

Key Concepts

Pattern 9: 3D Transforms and Modern CSS

3D Transform Utilities

Other Modern Features

Pattern 10: Component Class Composition with cn()

Key Concepts

Decision Framework

When to Use Which Styling Approach

Dark Mode Strategy

Theme Customization Scope

v3 to v4 Migration Decision

Integration Notes

RED FLAGS

CRITICAL REMINDERS

Related Skills

agents-inc/web-ui-vuetify

agents-inc/web-meta-framework-vitepress

agents-inc/web-meta-framework-docusaurus

agents-inc/web-forms-tanstack-form

agents-inc/web-styling-tailwind

$ install --global

Security Scan Results

SKILL.md

Tailwind CSS v4+ Patterns

CRITICAL: Before Using This Skill

Philosophy

Core Patterns

Pattern 1: CSS-First Setup and Configuration

Installation Options

Key Concepts

Pattern 2: Responsive Design with Breakpoint Variants

Key Concepts

Pattern 3: Dark Mode

Strategies

Key Concepts

Pattern 4: State Variants

Available Variants

Key v4 Changes

Pattern 5: Theme Customization with @theme

Namespaces

Key Concepts

Pattern 6: Custom Utilities with @utility

Types of Custom Utilities

Value Resolution

Pattern 7: Custom Variants with @custom-variant

Syntax Forms

Pattern 8: Container Queries

Key Concepts

Pattern 9: 3D Transforms and Modern CSS

3D Transform Utilities

Other Modern Features