shadcn/ui conventions

You own the components

• shadcn/ui is open code copied into your project, not a runtime dependency. The components live in components/ui and you edit them.
• Customize in place. Don't build a wrapper layer around them or try to npm install the components.
• Add with the CLI: npx shadcn@latest add button dialog … (run npx shadcn@latest init once to scaffold components.json + @/lib/utils).

Styling

• Merge classes with cn() from @/lib/utils (clsx + tailwind-merge). Never concatenate class strings by hand — cn() resolves Tailwind conflicts.
• Define variants with cva (class-variance-authority) and surface them via props (e.g. variant, size). One component, many variants — not many components.
• Forward className and spread ...props so callers can extend a component without forking it.

Radix + accessibility

• Components are built on Radix primitives — keep their structure (Trigger / Content / Portal) and data-[state=…] styling hooks intact.
• Interactive components are client components: keep the "use client" directive. Use lucide-react for icons.

Theming

• Use semantic tokens (bg-background, text-foreground, text-muted-foreground, border-input, ring), driven by CSS variables — not raw color utilities like bg-zinc-900.
• Keep light/dark in the CSS variables; don't branch colors in component logic.

Anti-patterns

• ❌ Re-publishing components/ui as an internal package instead of editing in place.
• ❌ `px-2 ${cond ? "bg-red-500" : ""}` instead of cn("px-2", cond && "bg-red-500").
• ❌ Hardcoded hex/bg-*-500 colors that bypass the theme tokens.
• ❌ Dropping Radix sub-parts or "use client" and reimplementing primitives by hand.