Review custom components and layouts against shadcn design patterns, visual style conventions (Vega, Nova, Maia, Lyra, Mira), composition rules, design token usage, and Radix/Base UI composition patterns. Use PROACTIVELY after writing or modifying any custom UI component, page layout, or variant of

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: 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. <button data slot="button" data variant={variant} data size={size} ). 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 <component . 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: 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 (< 768px design), progressive enhancement via md: , lg: Touch targets minimum ~44px on interactive elements min w 0 on flex children to prevent overflow Semantic HTML (buttons are <button , not styled <div ) 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 : Extend with new variants; don't modify the base layer. cn() Utility Combines clsx (conditionals) + tailwind merge (conflict resolution). Always use for className composition: 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 <code . 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 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](https://ui.shadcn.com) Component reference (live): npx shadcn@latest docs <component — returns current doc and example URLs Project context: npx shadcn@latest info json Theme creator: [ui.shadcn.com/create](https://ui.shadcn.com/create) TweakCN (interactive theme editor): [tweakcn.com](https://tweakcn.com)

shadcn-component-review