tailwind-refactor

Community Tailwind CSS Refactoring Best Practices Comprehensive code quality refactoring guide for Tailwind CSS applications targeting v4. Contains 50 rules across 8 categories, prioritized by migration urgency. Every transformation preserves the existing look and feel — this skill is purely about cleaner code, modern syntax, and v4 compatibility. Companion skills: Use tailwind-ui-refactor for visual design improvements and tailwind-responsive-ui for responsive layout patterns. When to Apply Before manual migration: Run npx @tailwindcss/upgrade first — it handles most configuration and renamed utility changes automatically. Then use this skill for patterns the automated tool does not cover. Reference these guidelines when: Migrating a project from Tailwind CSS v3 to v4 Cleaning up deprecated or renamed utility classes Consolidating verbose multi-class patterns Replacing arbitrary values with design tokens Removing @apply overuse in CSS files Modernizing syntax to v4 conventions Rule Categories by Priority Priority Category Impact Prefix 1 Configuration Migration CRITICAL config- 2 Deprecated Utility Replacement CRITICAL dep- 3 Renamed Utility Updates HIGH rename- 4 Class Consolidation HIGH class- 5 Arbitrary Value Cleanup MEDIUM-HIGH arb- 6 Syntax Modernization MEDIUM syntax- 7 @apply & Architecture Cleanup MEDIUM arch- 8 Modern Feature Adoption LOW-MEDIUM adopt- Quick Reference 1. Configuration Migration (CRITICAL) config-import-directive - Replace @tailwind directives with @import config-css-theme - Migrate tailwind.config.js to CSS @theme config-theme-function - Replace theme() function with CSS variables config-theme-inline - Use @theme inline for non-utility design tokens config-utility-directive - Replace @layer utilities with @utility config-postcss-plugin - Update PostCSS plugin to @tailwindcss/postcss config-content-autodetect - Remove manual content configuration config-custom-variant - Migrate addVariant to @custom-variant config-preflight-defaults - Account for Preflight default changes in v4 2. Deprecated Utility Replacement (CRITICAL) dep-opacity-modifiers - Replace -opacity- with opacity modifiers (/50) dep-flex-shorthand - Replace flex-shrink/flex-grow with shrink/grow dep-text-ellipsis - Replace overflow-ellipsis with text-ellipsis dep-decoration-utilities - Replace decoration-slice/clone with box-decoration- dep-transform-composites - Replace transform-none with individual resets dep-transition-properties - Update transition-[transform] to individual properties 3. Renamed Utility Updates (HIGH) rename-shadow-scale - Update shadow utilities to new scale rename-blur-scale - Update blur utilities to new scale rename-rounded-scale - Update border radius utilities to new scale rename-ring-width - Replace ring with ring-3 for v3 default rename-gradient-utilities - Replace bg-gradient- with bg-linear- rename-outline-hidden - Replace outline-none with outline-hidden 4. Class Consolidation (HIGH) class-size-utility - Replace matching w- h- with size- class-gap-over-space - Prefer gap- over space-x/y- in flex/grid class-inset-shorthand - Replace top/right/bottom/left with inset- class-border-color-explicit - Add explicit border color for v4 default change class-ring-color-explicit - Add explicit ring color for v4 default change class-redundant-display - Remove redundant display classes class-hidden-priority - Remove display overrides for hidden attribute class-container-utility - Replace container plugin config with @utility 5. Arbitrary Value Cleanup (MEDIUM-HIGH) arb-hex-to-theme - Replace arbitrary hex colors with theme tokens arb-spacing-to-scale - Replace arbitrary spacing with theme scale arb-dynamic-classes - Avoid dynamic class name construction arb-breakpoint-to-theme - Replace arbitrary breakpoints with @theme arb-zindex-to-scale - Replace arbitrary z-index with defined scale 6. Syntax Modernization (MEDIUM) syntax-css-variable-parens - Update CSS variable syntax from brackets to parentheses syntax-variant-stacking - Update variant stacking to left-to-right order syntax-important-modifier - Use trailing ! for important modifier syntax-grid-arbitrary - Use underscores in grid arbitrary values syntax-gradient-preservation - Reset gradient stops explicitly in variants syntax-hover-media-query - Account for hover variant media query wrapping 7. @apply & Architecture Cleanup (MEDIUM) arch-apply-to-component - Extract @apply blocks into framework components arch-layer-to-utility - Replace @layer components with @utility arch-scoped-reference - Use @reference for @apply in scoped styles arch-safelist-to-source - Replace safelist with @source inline() arch-domain-composition - Reserve Tailwind for primitives, compose for domain 8. Modern Feature Adoption (LOW-MEDIUM) adopt-container-queries - Use container queries instead of viewport breakpoints adopt-not-variant - Use not- variant for negated conditions adopt-in-variant - Use in-* variant to simplify parent-state styling adopt-field-sizing - Use field-sizing-content for auto-resizing textareas adopt-starting-variant - Use starting variant for entry animations without JS 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 Reference Files File Description references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information