shadcn-agents-cva-validator

name	shadcn-agents-cva-validator
description	Use when reviewing, validating, or auditing a shadcn ui component that uses class-variance-authority (cva), when an LLM has just produced a Button-like, Badge-like, Alert-like, or any other cva-driven component and you must verify the variant API before accepting the diff, when a consumer className does not visually win and you suspect cva merge order or a missing cn() call, when extending an existing shadcn component with a new variant or compoundVariant and you want a deterministic checklist before commit, when porting a hand-written variants-via-if-branches component to cva, when writing a custom primitive that should follow the shadcn convention, when verifying that VariantProps inference is exported so consumers can extend the component type, or when running a code-review pass on AI-generated cva code to catch the canonical mistakes (nested cn inside cva, compoundVariants placed before variants, missing defaultVariants, raw className concatenation, asChild without Slot, variant key typos that silently disable a default). Prevents the seven canonical cva failures : (1) variant definition shape wrong (string instead of class string or array), (2) compoundVariants placed in the wrong object position so the parser silently accepts but defaults never resolve, (3) defaultVariants missing or with a typo that no TypeScript check catches because cva values are stringly-typed, (4) VariantProps export missing so consumers cannot extend, (5) caller className concatenated via template string instead of merged via cn() so twMerge is bypassed and duplicate utilities leak, (6) asChild rendered without Radix Slot so polymorphic composition silently breaks, (7) cn() called INSIDE a cva variant string (no-op, cva already runs clsx internally on its inputs). Covers the 7-point validator checklist (base, variants shape, compoundVariants order, defaultVariants, VariantProps export, cn() merge, asChild Slot), per-checkpoint pass and fail criteria with verbatim code patterns, sample-code-to-verdict mappings for at least a dozen common cva shapes, the canonical shadcn Button reference template that all checks reduce to, the cva evaluation order (defaults, then variants, then compoundVariants, then caller className) and how to verify it from the diff alone, and the Companion Skills cross-links to shadcn-syntax-variant-cva (B3, reference) and shadcn-errors-styling-conflicts (B11, debugging). Keywords: cva validator, validate cva component, variant API check, cva correctness check, VariantProps validation, cn helper validation, compoundVariants order check, defaultVariants typo, validate variant code, review cva component, cva self-check, how do I verify a cva component, is my cva component correct, cva checklist, cva audit, class-variance-authority review, shadcn variant audit, variant code review, cva diff review, asChild Slot check, missing defaultVariants, variant prop not applying, override className not winning, template string concat variant, raw className concatenation, nested cn inside cva, cva inside cva, compoundVariants before variants, VariantProps not exported, why is my variant not applying, audit variant component before commit, pre-commit cva check.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui Agent : cva Variant API Validator

This skill is the deterministic checklist a code-review or pre-commit agent uses to verify that any cva-driven shadcn component is shaped correctly. It is a VALIDATOR, not a tutorial. For the underlying cva theory, ALWAYS read shadcn-syntax-variant-cva first. For debugging a className override that does not visually win, ALWAYS read shadcn-errors-styling-conflicts.

The validator answers exactly one question per checkpoint : PASS or FAIL. It does not propose creative refactors. When a check fails, the verdict cites the failing line and points to the canonical fix.

Quick Reference

Validator workflow (top of every review)

1. Locate the cva call (search for cva( in the diff or file).
2. Run the 7-point checklist from top to bottom in declared order.
3. Stop at the first FAIL and emit the verdict with line reference.
4. If all 7 pass, emit VERDICT: PASS plus a one-line summary.
5. When called on a multi-file diff, repeat per component file independently.

The 7 checks are ordered by failure frequency observed in real shadcn projects : base, variants shape, compoundVariants order, defaultVariants, VariantProps export, cn() merge, asChild Slot. The first three catch over half of every cva regression seen in shadcn-ui/ui issues.

The 7-point checklist (memorize)

#	Check	One-line pass criterion
1	Base	First positional argument to cva is a string OR a string array
2	Variants shape	Every variant value is a string OR a string array, never a function, never nested cn()
3	compoundVariants order	compoundVariants declared AFTER variants in the config object literal
4	defaultVariants	Every variant axis has an entry in defaultVariants (or explicit null)
5	VariantProps export	The cva return value is exported AND VariantProps<typeof X> is in the props type
6	cn() merge	Component returns className={cn(xVariants({ ..., className }))}, NEVER template-string concat
7