tailwind-v4

Tailwind CSS v4 Best Practices

Quick Reference

Vite Plugin Setup:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';
 
export default defineConfig

CSS Entry Point:

@theme Inline Directive:

Key Differences from v3

@theme Directive Modes

default (standard mode)

Generates CSS variables that can be referenced elsewhere:

Note: You can also use @theme default explicitly to mark theme values that can be overridden by non-default @theme declarations.

inline

Inlines values directly without CSS variables (better performance):

reference

Inlines values as fallbacks without emitting CSS variables:

OKLCH Color Format

OKLCH provides perceptually uniform colors with better consistency across hues:

• L (Lightness): 0% (black) to 100% (white)
• C (Chroma): 0 (gray) to ~0.4 (vibrant)
• H (Hue): 0-360 degrees (red → yellow → green → blue → magenta)

Examples:

CSS Variable Naming

Tailwind v4 uses double-dash CSS variable naming conventions:

No Config Files Needed

Tailwind v4 eliminates configuration files:

• No tailwind.config.js - Use @theme in CSS instead
• No postcss.config.js - Use @tailwindcss/vite plugin
• TypeScript support - Add @types/node for path resolution

Progressive Disclosure

• Setup & Installation: See references/setup.md for Vite plugin configuration, package setup, TypeScript config
• Theming & Design Tokens: See references/theming.md for @theme modes, color palettes, custom fonts, animations
• Dark Mode Strategies: See references/dark-mode.md for media queries, class-based, attribute-based approaches

Gates (setup verification)

Before recommending @theme choices, OKLCH tokens, or v4 utilities, confirm the project is actually on the v4 integration path:

1. Build wiring: The Vite config loads tailwindcss() from @tailwindcss/vite, and the CSS entry uses @import 'tailwindcss'. If this fails, stop — fix wiring per references/setup.md first.
2. Major versions: package.json lists tailwindcss (and @tailwindcss/vite when using Vite) at major 4, not a v3 PostCSS-only toolchain.
3. Theme source: New theme tokens live in @theme / @theme inline in CSS — not tailwind.config.js extend (v3). If a v3 config still drives the theme, migrating wiring takes precedence over token tweaks.

Decision Guide

When to use @theme inline vs default

Use @theme inline:

• Better performance (no CSS variable overhead)
• Static color values that won't change
• Animation keyframes with multiple values
• Utilities that need direct value inlining

Use @theme (default):

• Dynamic theming with JavaScript
• CSS variable references in custom CSS
• Values that change based on context
• Better debugging (inspect CSS variables in DevTools)

When to use @theme reference

Use @theme reference:

• Provide fallback values without CSS variable overhead
• Values that should work even if variable isn't defined
• Reducing :root bloat while maintaining utility support
• Combining with inline for direct value substitution

Common Patterns

Two-Tier Variable System

Semantic variables that map to design tokens:

Custom Font Configuration

Animation Keyframes