Tailwind

Community Tailwind CSS v4 Best Practices

Comprehensive performance optimization guide for Tailwind CSS v4 applications. Contains 44 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 [blocked] - Use Vite Plugin Over PostCSS
• build-css-import [blocked] - Use CSS Import Over @tailwind Directives
• build-content-detection [blocked] - Leverage Automatic Content Detection
• build-node-version [blocked] - Use Node.js 20+ for Optimal Performance
• build-postcss-simplify [blocked] - Remove Redundant PostCSS Plugins
• build-cli-package [blocked] - Use Correct CLI Package

2. CSS Generation (CRITICAL)

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

3. Bundle Optimization (HIGH)

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

4. Utility Patterns (HIGH)

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

5. Component Architecture (MEDIUM-HIGH)

• comp-avoid-apply-overuse [blocked] - Avoid Overusing @apply
• comp-reference-directive [blocked] - Use @reference for CSS Module Integration
• comp-utility-file-scope [blocked] - Understand Utility File Scope
• comp-smart-sorting [blocked] - Leverage Smart Utility Sorting
• comp-container-customize [blocked] - Customize Container with @utility
• comp-custom-variant [blocked] - Use @custom-variant for Custom Variant Definitions

6. Theming & Design Tokens (MEDIUM)

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

7. Responsive & Adaptive (MEDIUM)

• resp-mobile-first [blocked] - Use Mobile-First Responsive Design
• resp-container-queries [blocked] - Use Container Queries for Component-Level Responsiveness
• resp-custom-breakpoints [blocked] - Define Custom Breakpoints in @theme
• resp-hover-capability [blocked] - Pair Hover with Active for Touch-Friendly Interactions
• resp-logical-properties [blocked] - Use Logical Properties for RTL Support

8. Animation & Transitions (LOW-MEDIUM)

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

How to Use

Read individual reference files for detailed explanations and code examples:

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

Full Compiled Document

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

Reference Files