Use when reviewing a Tailwind CSS codebase for cross-rule violations, performing a pre-PR audit of changes that touch styling, validating a v3-to-v4 migration result, or running a periodic codebase health check across utility classes, plugin authoring, and configuration files. The agent acts as a Tailwind-specific code reviewer that enforces every rule documented in the sibling skills of this package, producing an actionable report that cites the authoritative sibling skill for each finding. Prevents the four highest-impact Tailwind code-review misses: dynamic template-literal class strings that compile cleanly but emit no CSS in production, scoped @apply blocks in Vue/Svelte/CSS-modules without @reference under v4, v3-only config keys (corePlugins, safelist, separator) silently ignored after a v4 upgrade, and bare border/ring/placeholder usage inheriting the wrong default colour post-migration. Covers the full rule catalogue (no dynamic class strings, no scoped @apply without @reference, no v3 keys in v4 con
Use when reviewing a Tailwind CSS codebase for cross-rule violations, performing a pre-PR audit of changes that touch styling, validating a v3-to-v4 migration result, or running a periodic codebase health check across utility classes, plugin authoring, and configuration files. The agent acts as a Tailwind-specific code reviewer that enforces every rule documented in the sibling skills of this package, producing an actionable report that cites the authoritative sibling skill for each finding. Prevents the four highest-impact Tailwind code-review misses: dynamic template-literal class strings that compile cleanly but emit no CSS in production, scoped @apply blocks in Vue/Svelte/CSS-modules without @reference under v4, v3-only config keys (corePlugins, safelist, separator) silently ignored after a v4 upgrade, and bare border/ring/placeholder usage inheriting the wrong default colour post-migration. Covers the full rule catalogue (no dynamic class strings, no scoped @apply without @reference, no v3 keys in v4 config, no undefined custom classes outside @layer, variant-stack order consistency, explicit border and ring colours, no em-dash in user-facing strings, deterministic prop-to-class mapping, twMerge ordering correctness, plugin theme() default-shipping), the report format (severity, file:line, rule citation, sibling-skill link, fix suggestion), the recursive scan pattern (TSX, JSX, Vue, Svelte, CSS, MDX), the v3-or-v4 detection heuristic, and integration into CI as a non-blocking advisory. Keywords: tailwind code review, tailwind validator, tailwind audit, tailwind linter, pre-PR check tailwind, post-migration audit, v3 v4 consistency check, cross-rule check tailwind, dynamic class detection, scoped @apply check, @reference missing, corePlugins leftover, safelist leftover, separator leftover, bare border bare ring, prop-to-class consistency, variant order check, twMerge audit, my codebase upgrade looks clean but, find all dynamic classes, find all scoped @apply, find tailwind antipatterns, tailwind health check, before I ship audit.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
Acts as a Tailwind-specific code reviewer. Reads the codebase, runs
every rule documented in the sibling skills, produces an actionable
report that cites the authoritative source per finding.
The validator does NOT modify code. It reports. The developer (or a
follow-up agent) applies fixes guided by the cited sibling skill.
How To Invoke
The user asks "validate my Tailwind code" or "audit this codebase for
Tailwind issues" or "run a pre-PR check on the styling changes". The
agent :
Detects v3 vs v4 (heuristic in Method 1, references/methods.md).
Runs each rule in the catalogue (Section : Rule Catalogue).
Emits the report in the standard format (Section : Report Format).
Detect : v3 or v4
Decision sources, in priority order :
package.jsondependencies.tailwindcss semver. ^3.x is v3.
^4.x is v4.
CSS entry file contains @import "tailwindcss" (v4) OR three
@tailwind directives (v3).
PostCSS config plugin is @tailwindcss/postcss (v4) OR
tailwindcss (v3).
Vite config imports @tailwindcss/vite (v4) OR uses the PostCSS
plugin (v3).
If signals conflict, report a Severity-Error mismatch FIRST. Mixed
configurations produce silent failures.
Fix : prepend @reference "../path/to/app.css"; inside the style
block.
Rule R-03 : Forbidden v3 Config Keys in v4 Project
Scans : tailwind.config.js, tailwind.config.ts
Detect : project is v4 AND config file contains any of
corePlugins, safelist, separator.
Severity : Warning (silently ignored, original intent lost)
Sibling skill : tailwind-errors-v4-migration, fallback to
tailwind-impl-migration-v3-v4
Fix :
corePlugins : remove and replace with ESLint rule or @source not
safelist : convert to @source inline("...") in CSS
separator : remove ; v4 fixes separator to :
Rule R-04 : Undefined Custom Class Outside @layer
Scans : .css
Detect : project is v3 and file contains a custom class
declaration (.classname { ... }) outside @layer base / @layer components / @layer utilities. Project is v4 and file contains a
custom class without @utility or @layer.
Fix : wrap in @layer components (v3) or rewrite as @utility
(v4).
Rule R-05 : Variant Stack Order
Scans : .tsx, .jsx, .vue, .svelte, .html
Detect : v4 project contains a class with two or more variants
that look v3-style. Common patterns : first:*:, last:*:,
hover:lg: (the lg should come first under v4 left-to-right rule for
breakpoints AT the variant level).
Severity : Warning (visual regression after v3 to v4)
Fix : add explicit colour (border-zinc-200, ring-blue-500,
placeholder-zinc-400) OR restore v3 defaults globally via @layer base (see method).
Rule R-07 : Em-Dash in User-Facing String
Scans : .tsx, .jsx, .vue, .svelte, .html, .mdx
Detect : literal — (U+2014) inside JSX text, attribute strings
that render to users (title, aria-label, placeholder), or
component children.
Severity : Info (typography standard ; CLAUDE.md project rule)
Sibling skill : (project rule, see workspace CLAUDE.md)
Fix : replace with ., ,, or rewrite the sentence. NEVER
replace with -.
Rule R-08 : Deterministic Prop-to-Class Mapping
Scans : .tsx, .jsx, .vue, .svelte
Detect : component receives a variant / color / size prop
and constructs the class via a switch statement, ternary chain, or
function call that returns differently-shaped strings per branch.
Severity : Info (maintainability ; not a bug, but harder to
audit)
Sibling skill : tailwind-core-design-system
Fix : refactor to a single object literal mapping prop value to
complete class string.
Rule R-09 : twMerge Order Mistake
Scans : .tsx, .jsx, .vue, .svelte
Detect : twMerge(...) or cn(...) call with conflicting
utilities where the LATER argument is the loser (e.g.
twMerge('p-4', 'p-2') resolves to p-2 ; if the intent was p-4
as the override, the argument order is wrong).
Severity : Info (requires intent inference ; flag for human
review only)
Sibling skill : tailwind-impl-tailwind-merge
Fix : reverse the argument order so the override is last.
Rule R-10 : Plugin Missing Default Theme Values
Scans : *.js, *.ts files exporting a Tailwind plugin
Detect : the plugin body calls theme('someNamespace') AND the
plugin's second-arg config does NOT define
theme.extend.someNamespace.
Severity : Warning (plugin works only when consumer happens to
configure the namespace, fails silently otherwise)
Sibling skill : tailwind-impl-plugins-custom
Fix : ship defaults via the plugin(fn, { theme: { ... } })
second argument.
The sibling skill name (NOT a URL ; the in-package skill reference)
A one-line suggested fix
Cross-Reference Index
Rule
Authoritative Skill
R-01 dynamic classes
tailwind-errors-dynamic-classes
R-02 scoped @apply
tailwind-impl-apply-directive
R-03 v3 keys in v4
tailwind-impl-migration-v3-v4
R-04 undefined custom class
tailwind-impl-config-v3, tailwind-impl-config-v4
R-05 variant stack order
tailwind-syntax-variants
R-06 bare border/ring
tailwind-impl-migration-v3-v4
R-07 em-dash
workspace CLAUDE.md
R-08 prop-to-class shape
tailwind-core-design-system
R-09 twMerge ordering
tailwind-impl-tailwind-merge
R-10 plugin theme defaults
tailwind-impl-plugins-custom
CI Integration
The validator is ADVISORY by default. Exit code is 0 unless errors
exceed the configured threshold. Sample GitHub Actions step :
-name:Tailwindauditrun:|
claude --skill tailwind-agents-validator . > tailwind-report.txt
cat tailwind-report.txt
# fail only if errors > 0
grep -q '^\[ERROR\]' tailwind-report.txt && exit 1 || exit 0
NEVER block PRs on info or warning levels. Errors (R-01, R-02)
indicate real production bugs and SHOULD block.
Sequencing With Sibling Skills
The validator is NOT a substitute for the per-area skills. When a
finding cites tailwind-errors-dynamic-classes, the developer (or
the follow-up agent) opens that skill for the full fix catalogue.
Recommended workflow :
Run tailwind-agents-validator.
For each error : open the cited skill, apply the documented fix.
Re-run the validator. Iterate until errors = 0.
Optional : address warnings and info as time allows.
References
references/methods.md : per-rule detection commands (grep, AST,
PostCSS) and the v3-or-v4 heuristic in detail
references/examples.md : sample input codebase plus the validator
report it should produce
references/anti-patterns.md : ten high-impact violations the
validator catches, with before/after
