Skip to content
Skills Library
Programming · Building & coding

tailwind-refactor

/tailwind-refactor

Tailwind CSS code refactoring patterns for v4 migration and anti-pattern cleanup. This skill should be used when refactoring Tailwind utility classes, migrating from v3 to v4, cleaning up deprecated utilities, consolidating verbose class patterns, or removing code smells — all without changing the visual output. Triggers on tasks involving Tailwind CSS cleanup, v4 migration, class refactoring, @apply removal, or utility modernization.

Repository
dot-skills ↗
Licence
MIT
Last repository change
15.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
54
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Tailwind CSS code refactoring patterns for v4 migration and anti-pattern cleanup. This skill should be used when refactoring Tailwind utility classes, migrating from v3 to v4, cleaning up deprecated utilities, consolidating verbose class patterns, or removing code smells — all without changing the visual output. Triggers on tasks involving Tailwind CSS cleanup, v4 migration, class refactoring, @apply removal, or utility modernization.

Original author description

Tailwind CSS code refactoring patterns for v4 migration and anti-pattern cleanup. This skill should be used when refactoring Tailwind utility classes, migrating from v3 to v4, cleaning up deprecated utilities, consolidating verbose class patterns, or removing code smells — all without changing the visual output. Triggers on tasks involving Tailwind CSS cleanup, v4 migration, class refactoring, @apply removal, or utility modernization.

How it works

  1. When to Apply
  2. Rule Categories by Priority
  3. Quick Reference
  4. How to Use
  5. Reference Files
Original SKILL.md headings · 123 lines, 797 words
SKILL.md preview
---
name: tailwind-refactor
description: Tailwind CSS code refactoring patterns for v4 migration and anti-pattern cleanup. This skill should be used when refactoring Tailwind utility classes, migrating from v3 to v4, cleaning up deprecated utilities, consolidating verbose class patterns, or removing code smells — all without changing the visual output. Triggers on tasks involving Tailwind CSS cleanup, v4 migration, class refactoring, @apply removal, or utility modernization.
---

# 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](../tailwind-ui-refactor/) for visual design improvements and [tailwind-responsive-ui](../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`](references/config-import-directive.md) - Replace @tailwind directives with @import
- [`config-css-theme`](references/config-css-theme.md) - Migrate tailwind.config.js to CSS @theme
- [`config-theme-function`](references/config-theme-function.md) - Replace theme() function with CSS variables
- [`config-theme-inline`](references/config-theme-inline.md) - Use @theme inline for non-utility design tokens
- [`config-utility-directive`](references/config-utility-directive.md) - Replace @layer utilities with @utility
- [`config-postcss-plugin`](references/config-postcss-plugin.md) - Update PostCSS plugin to @tailwindcss/postcss
- [`config-content-autodetect`](references/config-content-autodetect.md) - Remove manual content configuration
- [`config-custom-variant`](references/config-custom-variant.md) - Migrate addVariant to @custom-variant
- [`config-preflight-defaults`](references/config-preflight-defaults.md) - Account for Preflight default changes in v4

### 2. Deprecated Utility Replacement (CRITICAL)

- [`dep-opacity-modifiers`](references/dep-opacity-modifiers.md) - Replace *-opacity-* with opacity modifiers (/50)
- [`dep-flex-shorthand`](references/dep-flex-shorthand.md) - Replace flex-shrink/flex-grow with shrink/grow
- [`dep-text-ellipsis`](references/dep-text-ellipsis.md) - Replace overflow-ellipsis with text-ellipsis
- [`dep-decoration-utilities`](references/dep-decoration-utilities.md) - Replace decoration-slice/clone with box-decoration-*
- [`dep-transform-composites`](references/dep-transform-composites.md) - Replace transform-none with individual resets
- [`dep-transition-properties`](references/dep-transition-properties.md) - Update transition-[transform] to individual properties

### 3. Renamed Utility Updates (HIGH)

- [`rename-shadow-scale`](references/rename-shadow-scale.md) - Update shadow utilities to new scale
- [`rename-blur-scale`](references/rename-blur-scale.md) - Update blur utilities to new scale
- [`rename-rounded-scale`](references/rename-rounded-scale.md) - Update border radius utilities to new scale
- [`rename-ring-width`](references/rename-ring-width.md) - Replace ring with ring-3 for v3 default
- [`rename-gradient-utilities`](references/rename-gradient-utilities.md) - Replace bg-gradient-* with bg-linear-*
- [`rename-outline-hidden`](references/rename-outline-hidden.md) - Replace outline-none with outline-hidden

### 4. Class Consolidation (HIGH)

- [`class-size-utility`](references/class-size-utility.md) - Replace matching w-* h-* with size-*
- [`class-gap-over-space`](references/class-gap-over-space.md) - Prefer gap-* over space-x/y-* in flex/grid
- [`class-inset-shorthand`](references/class-inset-shorthand.md) - Replace top/right/bottom/left with inset-*
- [`class-border-color-explicit`](references/class-border-color-explicit.md) - Add explicit border color for v4 default change
- [`class-ring-color-explicit`](references/class-ring-color-explicit.md) - Add explicit ring color for v4 default change
- [`class-redundant-display`](references/class-redundant-display.md) - Remove redundant display classes
- [`class-hidden-priority`](references/class-hidden-priority.md) - Remove display overrides for hidden attribute
- [`class-container-utility`](references/class-container-utility.md) - Replace container plugin config with @utility

### 5. Arbitrary Value Cleanup (MEDIUM-HIGH)

- [`arb-hex-to-theme`](references/arb-hex-to-theme.md) - Replace arbitrary hex colors with theme tokens
- [`arb-spacing-to-scale`](references/arb-spacing-to-scale.md) - Replace arbitrary spacing with theme scale
- [`arb-dynamic-classes`](references/arb-dynamic-classes.md) - Avoid dynamic class name construction
- [`arb-breakpoint-to-theme`](references/arb-breakpoint-to-theme.md) - Replace arbitrary breakpoints with @theme
- [`arb-zindex-to-scale`](references/arb-zindex-to-scale.md) - Replace arbitrary z-index with defined scale

### 6. Syntax Modernization (MEDIUM)

- [`syntax-css-variable-parens`](references/syntax-css-variable-parens.md) - Update CSS variable syntax from brackets to parentheses
- [`syntax-variant-stacking`](references/syntax-variant-stacking.md) - Update variant stacking to left-to-right order
- [`syntax-important-modifier`](references/syntax-important-modifier.md) - Use trailing ! for important modifier
- [`syntax-grid-arbitrary`](references/syntax-grid-arbitrary.md) - Use underscores in grid arbitrary values
- [`syntax-gradient-preservation`](references/syntax-gradient-preservation.md) - Reset gradient stops explicitly in variants
- [`syntax-hover-media-query`](references/syntax-hover-media-query.md) - Account for hover variant media query wrapping

### 7. @apply & Architecture Cleanup (MEDIUM)

- [`arch-apply-to-component`](references/arch-apply-to-component.md) - Extract @apply blocks into framework components
- [`arch-layer-to-utility`](references/arch-layer-to-utility.md) - Replace @layer components with @utility
- [`arch-scoped-reference`](references/arch-scoped-reference.md) - Use @reference for @apply in scoped styles
- [`arch-safelist-to-source`](references/arch-safelist-to-source.md) - Replace safelist with @source inline()
- [`arch-domain-composition`](references/arch-domain-composition.md) - Reserve Tailwind for primitives, compose for domain

### 8. Modern Feature Adoption (LOW-MEDIUM)

- [`adopt-container-queries`](references/adopt-container-queries.md) - Use container queries instead of viewport breakpoints
- [`adopt-not-variant`](references/adopt-not-variant.md) - Use not-* variant for negated conditions
- [`adopt-in-variant`](references/adopt-in-variant.md) - Use in-* variant to simplify parent-state styling
- [`adopt-field-sizing`](references/adopt-field-sizing.md) - Use field-sizing-content for auto-resizing textareas
- [`adopt-starting-variant`](references/adopt-starting-variant.md) - Use starting variant for entry animations without JS

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |
Files in this package (54)
  • SKILL.md 8 KB
  • metadata.json 1 KB
  • assets/templates/_template.md 1 KB
  • references/_sections.md 2 KB
  • references/adopt-container-queries.md 1 KB
  • references/adopt-field-sizing.md 2 KB
  • references/adopt-in-variant.md 2 KB
  • references/adopt-not-variant.md 2 KB
  • references/adopt-starting-variant.md 1 KB
  • references/arb-breakpoint-to-theme.md 1 KB
  • references/arb-dynamic-classes.md 1 KB
  • references/arb-hex-to-theme.md 1 KB
  • references/arb-spacing-to-scale.md 1 KB
  • references/arb-zindex-to-scale.md 2 KB
  • references/arch-apply-to-component.md 1 KB
  • references/arch-domain-composition.md 2 KB
  • references/arch-layer-to-utility.md 2 KB
  • references/arch-safelist-to-source.md 1 KB
  • references/arch-scoped-reference.md 1 KB
  • references/class-border-color-explicit.md 1 KB
  • references/class-container-utility.md 1 KB
  • references/class-gap-over-space.md 1 KB
  • references/class-hidden-priority.md 1 KB
  • references/class-inset-shorthand.md 1 KB
  • references/class-redundant-display.md 2 KB
  • references/class-ring-color-explicit.md 1 KB
  • references/class-size-utility.md 1 KB
  • references/config-content-autodetect.md 1 KB
  • references/config-css-theme.md 1 KB
  • references/config-custom-variant.md 1 KB
  • references/config-import-directive.md 1 KB
  • references/config-postcss-plugin.md 1 KB
  • references/config-preflight-defaults.md 2 KB
  • references/config-theme-function.md 1 KB
  • references/config-theme-inline.md 1 KB
  • references/config-utility-directive.md 1 KB
  • references/dep-decoration-utilities.md 1 KB
  • references/dep-flex-shorthand.md 1 KB
  • references/dep-opacity-modifiers.md 1 KB
  • references/dep-text-ellipsis.md 1 KB
  • references/dep-transform-composites.md 1 KB
  • references/dep-transition-properties.md 1 KB
  • references/rename-blur-scale.md 1 KB
  • references/rename-gradient-utilities.md 1 KB
  • references/rename-outline-hidden.md 1 KB
  • references/rename-ring-width.md 1 KB
  • references/rename-rounded-scale.md 1 KB
  • references/rename-shadow-scale.md 1 KB
  • references/syntax-css-variable-parens.md 1 KB
  • references/syntax-gradient-preservation.md 1 KB
  • references/syntax-grid-arbitrary.md 1 KB
  • references/syntax-hover-media-query.md 2 KB
  • references/syntax-important-modifier.md 1 KB
  • references/syntax-variant-stacking.md 1 KB

Versions

The database has no other skills named tailwind-refactor.

Database snapshot: 13.11.2026 · package version 5c49a3d363c7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tailwind-utility-classes
    Use when working with Tailwind CSS utility classes for layout, spacing, typography, colors, and visual effects. Covers utility-first CSS patterns and class composition.
  • 100tailwind-ui-refactor
    Refactoring UI design patterns for Tailwind CSS applications. This skill should be used when writing, reviewing, or refactoring HTML with Tailwind utility classes to improve visual hierarchy, spacing, typography, color, depth, and polish. Triggers on tasks involving UI cleanup,…
  • 100tailwind-patterns
    Provides Tailwind CSS v4 patterns for CSS-first configuration, container queries, design tokens, and utility-first component architecture. Use when working with Tailwind CSS files or when the user mentions Tailwind, Tailwind v4, or utility-first CSS.
  • 100tailwind-css
    Tailwind CSS v4 patterns: CSS-first config, utility classes, component variants, v3 migration. Use when styling with Tailwind, configuring @theme tokens, using tailwind-variants/CVA, migrating v3 to v4, or fixing Tailwind styles and dark mode.
  • 100tailwindcss
    Tailwind CSS v4 utility-first discipline: CSS-first configuration, design tokens via @theme, and principled class composition. Invoke whenever task involves any interaction with Tailwind CSS — writing, reviewing, refactoring, debugging, or understanding utility classes, theme…
  • 90tailwind-v4
    Tailwind CSS v4 usage guide and v3-to-v4 differences. This skill should be used when writing, reviewing, or refactoring any Tailwind CSS code in this repo. Triggers on tasks involving Tailwind classes, @theme blocks, CSS-first configuration, or cleanup of v3-era syntax.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.