tailwind

Tailwind Labs Tailwind CSS v4 Best Practices

Comprehensive performance optimization guide for Tailwind CSS v4 applications, maintained by Tailwind Labs. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Configuring Tailwind CSS v4 build tooling (Vite plugin, PostCSS, CLI)
• Writing or migrating styles using v4's CSS-first approach
• Optimizing CSS bundle size and build performance
• Implementing responsive designs with breakpoints or container queries
• Setting up theming with @theme directive and design tokens

Rule Categories by Priority

Quick Reference

1. Build Configuration (CRITICAL)

• `build-vite-plugin` - Use Vite Plugin Over PostCSS
• `build-css-import` - Use CSS Import Over @tailwind Directives
• `build-content-detection` - Leverage Automatic Content Detection
• `build-node-version` - Use Node.js 20+ for the upgrade tool
• `build-postcss-simplify` - Remove Redundant PostCSS Plugins
• `build-cli-package` - Use Correct CLI Package

2. CSS Generation (CRITICAL)

• `gen-css-first-config` - Use CSS-First Configuration Over JavaScript
• `gen-avoid-theme-bloat` - Avoid Excessive Theme Variables
• `gen-oklch-colors` - Use OKLCH Color Space for Vivid Colors
• `gen-utility-directive` - Use @utility for Custom Utilities
• `gen-dynamic-utilities` - Use Dynamic Utility Values
• `gen-css-variable-syntax` - Use Parentheses for CSS Variable References

3. Bundle Optimization (HIGH)

• `bundle-remove-unused-plugins` - Remove Built-in Plugins
• `bundle-avoid-preprocessors` - Avoid Sass/Less Preprocessors
• `bundle-css-minification` - Enable CSS Minification in Production
• `bundle-avoid-cdn-production` - Avoid Play CDN in Production
• `bundle-split-critical-css` - Extract Critical CSS for Initial Render

4. Utility Patterns (HIGH)

• `util-renamed-utilities` - Use Renamed Utility Classes
• `util-important-modifier` - Use Trailing Important Modifier
• `util-variant-stacking` - Use Left-to-Right Variant Stacking
• `util-explicit-colors` - Use Explicit Border and Ring Colors
• `util-opacity-modifier` - Use Slash Opacity Modifier
• `util-gradient-via-none` - Use via-none to Reset Gradient Stops

5. Component Architecture (MEDIUM-HIGH)

• `comp-avoid-apply-overuse` - Avoid Overusing @apply
• `comp-reference-directive` - Use @reference for CSS Module Integration
• `comp-utility-file-scope` - Understand Utility File Scope
• `comp-smart-sorting` - Leverage Smart Utility Sorting
• `comp-container-customize` - Customize Container with @utility

6. Theming & Design Tokens (MEDIUM)

• `theme-semantic-tokens` - Use Semantic Design Token Names
• `theme-dark-mode-class` - Use Class-Based Dark Mode for Control
• `theme-prefix-variables` - Use Prefix for Variable Namespacing
• `theme-runtime-variables` - Leverage Runtime CSS Variables
• `theme-color-scheme` - Set color-scheme for Native Dark Mode

7. Responsive & Adaptive (MEDIUM)

• `resp-mobile-first` - Use Mobile-First Responsive Design
• `resp-container-queries` - Use Container Queries for Component-Level Responsiveness
• `resp-custom-breakpoints` - Define Custom Breakpoints in @theme
• `resp-hover-capability` - Understand Hover Behavior on Touch Devices
• `resp-logical-properties` - Use Logical Properties for RTL Support

8. Animation & Transitions (LOW-MEDIUM)

• `anim-gpu-accelerated` - Use GPU-Accelerated Transform Properties
• `anim-starting-style` - Use @starting-style for Entry Animations
• `anim-gradient-interpolation` - Use OKLCH Gradient Interpolation
• `anim-3d-transforms` - Use Built-in 3D Transform Utilities

How to Use

Read individual reference files for detailed explanations and code examples:

Full Compiled Document

For a complete guide with all rules expanded, see AGENTS.md.

Reference Files