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 Optimal Performance
• •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:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules

Full Compiled Document

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

Reference Files