tailwind-best-practices

Tailwind best practices

Contract

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.