shadcn/ui Community Best Practices

58 rules across 10 categories for shadcn/ui, prioritized by impact to guide automated refactoring and code generation.

Stack baseline

Rules target current shadcn/ui: Tailwind CSS v4 (CSS-first, no tailwind.config.*, tokens in @theme inline), React 19 (ref as a prop, data-slot attributes), the unified radix-ui package, OKLCH color tokens, tw-animate-css, Field + React Hook Form Controller forms, and Bun (bunx --bun shadcn@latest ...). Examples use the Radix base (--base radix); the CLI also supports a Base UI base (--base base), where triggers take a render prop instead of asChild. For a Tailwind v3 project, keep the existing config and follow the shadcn upgrade guide first.

Setup mode

Use when installing, repairing or migrating shadcn/ui (new project, existing project, Tailwind v3 to v4). Follow references/_setup-mode.md: pick the bunx --bun shadcn@latest init path, then wire Tailwind v4 CSS-first (@theme inline, @custom-variant dark), components.json with an empty tailwind.config, the cn() helper, and the validation checklist. Do only the requested setup and confirm before overwriting existing styles, config or components. After setup, the rules below apply.

When to Apply

• Installing and configuring shadcn/ui in a project (see Setup mode)
• Writing new shadcn/ui components or composing primitives
• Implementing forms with React Hook Form and Zod validation
• Building data tables or handling large dataset displays
• Customizing themes or adding dark mode support
• Reviewing code for accessibility compliance