Shadcn Component Review

shadcn Component Review

Systematic audit process for ensuring custom components align with shadcn design patterns, the project's chosen visual style, and modern composition conventions.

How This Complements the Official shadcn Skill

The official shadcn skill (shipped with CLI v4) enforces rules at generation time — telling agents "use gap-* not space-y-*, use semantic colors, use size-* for equal width/height," and so on. That's correct behavior when writing new code.

This skill is for post-hoc audit — reviewing components that already exist (written by Claude, by a teammate, by a previous iteration) against those same rules plus the visual-style-specific patterns that vary by theme (Vega spacing differs from Maia differs from Mira). When the two skills both apply, the official handles forward-generation and this one handles retrospective review. They don't conflict — they check the same rules from different directions.

Core Principle

Reviews catch drift. Even with the official skill enforcing rules during generation, components drift over time: someone copies from an older project, an LLM suggests space-y-4 and nobody catches it, a component was built before the project standardized on Maia, or a contributor uses Tailwind's color scale instead of semantic tokens. This skill finds those issues systematically.

When to Trigger

Proactive triggers (activate after components are written):

• Claude just finished writing or modifying a custom component
• User says "I built this" and pastes a component
• User asks to add styling to an existing element
• User is iterating on a layout

Explicit triggers (user directly requests review):

• "Review this component"
• "Check my spacing"
• "Is this shadcn-idiomatic?"
• "Does this follow the patterns?"
• "Audit this layout"

Before Reviewing: Project Context

Before applying theme-specific patterns, understand the project. If the shadcn CLI is available, run:

npx shadcn@latest info --json

This returns: framework (Next.js / Vite / etc.), Tailwind version, base library (radix or base), installed components, icon library, resolved file paths, and the current style. Use this output to:

• Match spacing/shape expectations to the project's visual style
• Apply the correct composition pattern for the primitive base (Radix vs Base UI — APIs differ)
• Know which components are already installed vs suggesting installs

If the CLI isn't available, infer from components.json directly, or ask the user: "Which visual style is this project using — Vega, Nova, Maia, Lyra, or Mira?"

Review Workflow

Step 1: Structure & Composition

Check the component is structured using shadcn conventions.

data-slot attributes. Every semantic element within a component should carry a data-slot attribute naming its role. This enables styling hooks, testing selectors, and consistent theming. Confirmed current pattern in shadcn source (e.g. ``).

Composition, not modification. Custom components should compose primitives from @/components/ui/*, not fork and modify them. If a primitive needs different behavior, wrap it; don't edit the source.

Primitive base awareness. If the project uses Radix (--base radix), expect asChild and Slot patterns, Radix data-state attributes. If Base UI (--base base), expect different composition APIs. Reference the current docs for the installed primitive: npx shadcn@latest docs .

Step 2: Spacing Audit

Spacing is where most drift happens. Check against the project's visual style — see [references/theme-styles.md](references/theme-styles.md) for per-style patterns.

Universal rules (apply to all themes):

• Use gap-* in flex/grid containers, never space-y-* / space-x-* or margins
• Use Tailwind's standard spacing scale (multiples of 4px: 1, 1.5, 2, 4, 6, 8 — avoid 3, 5, 7)
• Use size-* when width and height are equal (size-10 not w-10 h-10)
• Responsive spacing uses gap-X md:gap-Y pattern

Style-specific rules: density and radius expectations differ by style. Reference [references/theme-styles.md](references/theme-styles.md) for the specifics.

Step 3: Design Tokens

Verify semantic tokens only — no hardcoded Tailwind color scale values.

| Category | Use | Avoid | |---|---|---| | Text color | text-foreground, text-muted-foreground, text-primary | text-neutral-500, text-gray-900, text-slate-700 | | Background | bg-background, bg-card, bg-muted, bg-accent | bg-gray-100, bg-white, bg-neutral-50 | | Border | border-border, border-input | border-gray-200, border-neutral-300 | | Border radius | rounded-md, rounded-lg (uses --radius) | rounded-[20px], rounded-[8px] |

Quick grep to flag hardcoded colors:

grep -rE '\b(neutral|gray|slate|zinc|stone)-[0-9]{2,3}\b' 

Step 4: Composability

Check the component can be reused without modification.

• Takes a className prop merged via cn()
• Exposes variants via CVA where variation is likely
• Doesn't hardcode content; accepts children or content-shaped props
• Isn't tightly coupled to a specific data model or route

Step 5: Responsive & Accessibility

• Mobile-first baseline (, not styled `)
• Focus-visible states present (focus-visible:ring-*, focus-visible:border-*)
• Motion respects motion-safe: / prefers-reduced-motion

See [references/review-checklist.md](references/review-checklist.md) for the expanded checklist.

Foundational Patterns

CVA (Class Variance Authority)

Variants are declared via cva(), typed via VariantProps:

import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-all",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border bg-background hover:bg-accent",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3 text-xs",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

type ButtonProps = React.ComponentProps & VariantProps

Extend with new variants; don't modify the base layer.

cn() Utility

Combines clsx (conditionals) + tailwind-merge (conflict resolution). Always use for className composition:

import { cn } from "@/lib/utils"

Theme-Aware Styling

shadcn themes use CSS variables (OKLCH-based since 2025). Key variables: --radius, --background, --foreground, --primary, --secondary, --accent, --muted, --card, --popover, --destructive, --border, --input, --ring.

Use Tailwind's semantic class names that map to these (rounded-md → --radius, bg-primary → --primary) rather than hardcoded values.

Animation

Brief conventions:

• Hover/focus/active: Tailwind transitions, 150ms
• Color/state transitions: 200ms
• Enter/exit of DOM elements: Tailwind animate-in/animate-out with Radix data-state, or Motion's AnimatePresence
• Always respect motion-safe: for transform-based animations

See [references/animation-patterns.md](references/animation-patterns.md) for the full guide.

Visual Styles Reference

shadcn ships five official visual styles, configurable via npx shadcn create or via preset codes (CLI v4):

| Style | Density | Shape | Canonical use | |---|---|---|---| | Vega | Standard | Classic | Default shadcn look | | Nova | Compact | Standard | Dense UIs, data-heavy apps | | Maia | Generous | Soft/rounded (often pill) | Consumer apps, friendly interfaces | | Lyra | Standard | Boxy/sharp | Developer tools, mono fonts | | Mira | Dense | Compact | Admin dashboards, power users |

Each style affects spacing scale, border radius, and component dimensions. See [references/theme-styles.md](references/theme-styles.md) for per-style spacing patterns and common mistakes.

Presets (new in CLI v4) pack style + theme + fonts + icons + radius into a single short code applied via npx shadcn@latest apply --preset . When reviewing, check the project's preset if configured — it's the source of truth for many of these conventions.

Scope: What This Skill Does NOT Enforce

Be explicit about the difference between shadcn canon and project-specific conventions. This skill reviews against shadcn canon. Project-specific conventions (e.g. "our team always uses gap-4 between form fields") belong in the project's own style guide or a project-specific skill, not this one.

When in doubt, cite the source: "shadcn components use data-slot — see the button source at ui.shadcn.com/docs/components/button" vs "your project consistently uses gap-4 between form fields."

Output Format

A good review:

1. Summarizes what was reviewed in one line
2. Flags issues grouped by category (structure, spacing, tokens, composability, responsive/a11y)
3. Severity-marks each issue: ✅ passes, ⚠️ suggestion, ❌ blocking
4. Shows the fix inline where the fix is short and obvious; references the relevant pattern file where the fix is nuanced
5. Offers to apply fixes if the user wants

Keep it scannable. Don't belabor passing items — a single ✅ summary line for what's good is enough.

Example Review Output

## Review: ``

**Structure** ✅ `data-slot` present, composition clean
**Spacing** ⚠️ Uses `space-y-4` in flex container — swap to `gap-4`
**Tokens** ❌ `text-neutral-500` on line 12 — use `text-muted-foreground`
**Composability** ✅ Accepts className, variant props via CVA
**Responsive/a11y** ⚠️ Missing `min-w-0` on flex child (may overflow on narrow screens)

Fixes:
- Line 8: `space-y-4` → `gap-4`
- Line 12: `text-neutral-500` → `text-muted-foreground`
- Line 18: Add `min-w-0` to wrapping ``

Want me to apply these?

Reference Files

• [references/theme-styles.md](references/theme-styles.md) — Per-style spacing, shape, and common mistakes
• [references/review-checklist.md](references/review-checklist.md) — Expanded audit checklist by category
• [references/animation-patterns.md](references/animation-patterns.md) — Timing, easing, Radix data-state, Motion patterns

Resources

• Official shadcn docs: ui.shadcn.com
• Component reference (live): npx shadcn@latest docs — returns current doc and example URLs
• Project context: npx shadcn@latest info --json
• Theme creator: ui.shadcn.com/create
• TweakCN (interactive theme editor): tweakcn.com

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mattbx
• Source: mattbx/shadcn-skills
• License: MIT

Install and usage instructions live in the source repository linked above.