tailwind-agents-validator

name	tailwind-agents-validator
description	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+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind Validator : Cross-Skill Consistency Agent

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 :

1. Detects v3 vs v4 (heuristic in Method 1, references/methods.md).
2. Runs each rule in the catalogue (Section : Rule Catalogue).
3. Emits the report in the standard format (Section : Report Format).

Detect : v3 or v4

Decision sources, in priority order :

1. package.json dependencies.tailwindcss semver. ^3.x is v3. ^4.x is v4.
2. CSS entry file contains @import "tailwindcss" (v4) OR three @tailwind directives (v3).
3. PostCSS config plugin is @tailwindcss/postcss (v4) OR tailwindcss (v3).
4. 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.

Mixed-state cross-link : tailwind-impl-migration-v3-v4.

Rule Catalogue

Each rule names a check, the file types it scans, the sibling skill that documents the rule, and the severity.

Rule R-01 : No Dynamic Template-Literal Class Strings

Scans : .tsx, .jsx, .vue, .svelte, .astro, .mdx

Detect : grep for className=`...${...}...` and class="...{{ ...?... }}...{{ ... }}" patterns that build a class fragment from a variable.

Severity : Error (production bug, classes silently missing)

Sibling skill : tailwind-errors-dynamic-classes

Fix : static map per Method 1 of the sibling skill.

Rule R-02 : Scoped @apply Without @reference (v4 only)

: , ,