---
name: tailwind-best-practices
description: 'Use when writing, editing, reviewing, or auditing Tailwind classes, components, or configuration. Reorders and deduplicates classes, replaces arbitrary values with project tokens, and checks component extraction. Not for general CSS without Tailwind.'
---

# Tailwind best practices

## Contract

| Field | Bound contract |
|---|---|
| Trigger | User asks to write, edit, review, clean, refactor, or audit Tailwind classes, components, or configuration. |
| Authority | Reversible local writes only. Edit class lists and component variants in place; every mutation is reversible by restoring the prior class string or file content. |
| Side effect | Edits class lists and component variants; flags ad-hoc tokens, @apply-heavy styles, magic values, and missing minification. |
| Done | Token and component prerequisites exist; unnecessary utilities, semantics, ordering, @apply avoidance, and fixed variants are checked with version-aware minification. |

## Inputs

- One or more files containing Tailwind class strings, component definitions, or a Tailwind configuration file.
- Optional target Tailwind CSS version; defaults to the version declared in the project's `package.json` or Tailwind configuration.

## Refusal

- No Tailwind config or dependency found: stop before editing. Report the missing prerequisite. Modify no files.
- Class string parse failure: skip the malformed string. Record its file and line, then continue.
- Ambiguous utility replacement: keep the original utility and flag it for human review. Do not guess.
- Required `@apply` block: leave an `@apply` inside a pseudo-element or `@layer` unchanged and record why.

## Procedure

1. **Identify the Tailwind version.** Read `package.json` or the Tailwind configuration to determine the installed major version. Done when: the version is known or the missing prerequisite is reported.
2. **Scan class strings.** Locate every `class`, `className`, `class:list`, template literal containing utility classes, and `@apply` directive in the supplied files. Done when: every supplied file has been scanned.
3. **Remove unnecessary utilities.** Delete utilities that duplicate another utility in the same string and breakpoint scope. Delete utilities overridden by a later utility in the same group. Done when: no known duplicate or overridden utility remains.
4. **Enforce semantic utility use.** Replace arbitrary value brackets with the nearest named utility when one exists. Replace raw color literals with the project's design-token color scale when defined. Done when: each arbitrary value is replaced or retained with a reason.
5. **Reorder class strings.** Group utilities in this order: layout, flexbox/grid, spacing, sizing, typography, backgrounds, borders, effects, filters, tables, transitions/transforms, interactivity, accessibility. Sort alphabetically within each category. Done when: every parsed class string follows the order.
6. **Extract repeated patterns into components.** When three or more identical class strings appear across files, propose a reusable component or an `@apply`-free utility class. Record the extraction but do not apply it when the project lacks a component directory. Done when: repeated patterns are extracted or flagged.
7. **Minimize `@apply`.** Replace each `@apply` block with inline utilities when the same combination has a direct expression. Keep blocks required by a pseudo-element or `@layer` and record why. Done when: every block is converted or justified.
8. **Check fixed variants.** Flag responsive variants whose fixed pixel breakpoints conflict with `theme.screens`. Done when: every mismatch is reported.
9. **Verify minification readiness.** Check for `cssnano`, `lightningcss`, or Tailwind's built-in minification in v4+. Done when: minification is confirmed or the gap is reported.
10. **Emit the report.** Record each file changed, utility counts removed/reordered/replaced, and every flag. Done when: the report accounts for every edit and unresolved item.

## Failure modes

- Partial result: completed file edits remain. The user can restore prior content through version control; do not roll back successful edits because another class string could not be parsed.

## Output

Edited files, then a summary report ordered by file with utilities removed, reordered, arbitrary values replaced, `@apply` blocks converted, fixed-variant flags, and minification gaps.