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