shadcn/ui best practices

Use when building or reviewing UI with shadcn/ui.

Mental model

• shadcn/ui is not a traditional npm component library. It is a code distribution system and component architecture for building your own UI layer.
• Treat generated components as application code you own, not vendor code you are afraid to edit.
• Keep the design system explicit: tokens, variants, composition patterns, and project conventions should be understandable from the codebase itself.

Project setup

• Keep components.json accurate; it is the source of truth for framework, aliases, base library, icon library, and styling decisions.
• Use the shadcn CLI intentionally for initialization, adding components, docs lookup, migrations, and registry work.
• Prefer the documented project setup path for the current framework rather than manually recreating the install flow.

Base choice