Tailwind Refactor

This is your companion for moving a Tailwind project from v3 to v4 without breaking the visual output. Run the official upgrade CLI first, then apply this for the patterns it misses: consolidating verbose classes, killing @apply overuse, replacing arbitrary values with tokens, and modernizing syntax. It's organized into 50 rules across 8 categories with clear priorities, from critical config migrations to optional modern features like container queries. The architectural guidance is solid, especially the advice to reserve Tailwind for primitives and compose at the domain level. If you're doing a major version migration or inheriting a messy Tailwind codebase, this gives you a systematic cleanup checklist.

skills.sh installs: 314
GitHub stars: 222
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add pproenca/dot-skills --skill tailwind-refactor --agent claude-code

Installs into .claude/skills of the current project.

Files

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: