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

tailwind-refactor