/tailwind-best-practices

name: tailwind-best-practices
description: 'Use when writing, editing, cleaning, or refactoring Tailwind classes, components, or configuration. Not for read-only audits of Tailwind code, or general CSS without Tailwind.'
disable-model-invocation: true

Tailwind best practices

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to write, edit, clean, or refactor Tailwind classes, components, or configuration. Read-only review or audit requests are out of scope. | | Authority | Reversible local: writes only class lists and component variants in place; rollback is undo. No remote mutation. 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.
• Read-only review or audit requested with no edits: out of scope. Report that this skill runs only as a write, edit, clean, or refactor pass, and modify no files.

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.