Build UI Components with shadcn/ui

Governs correct usage of the shadcn/ui CLI and component library: adding components from shadcn/ui or community registries, styling and composing existing components, initializing new projects or switching design-system presets, and retrieving component documentation. It injects live project context - installed components, aliases, Tailwind version, icon library, framework - via npx shadcn@latest info --json and enforces four core principles: use existing components before writing custom UI, compose rather than reinvent (a settings page is Tabs + Card + form controls), prefer built-in variants over custom styles, and use semantic color tokens like bg-primary instead of raw values like bg-blue-500. It documents "always enforced" critical rules across five linked rule files covering styling and Tailwind (no space-x-*/space-y-*, size-* for equal dimensions, cn() for conditional classes, no manual z-index on overlay components), forms and inputs (FieldGroup/Field instead of raw divs, data-invalid/aria-invalid for validation state), component structure (items must live inside their Group, Dialog/Sheet/Drawer require a Title for accessibility, Avatar needs AvatarFallback), preferring built-in components like Alert, Empty, Skeleton, and Badge over custom markup, and icon conventions such as data-icon placement and passing icon components as objects rather than string keys. It also defines a nine-step workflow - get project context, check installed components before adding duplicates, search the registry, fetch docs and examples before coding, install or update, fix hardcoded import paths from third-party registries, review every added file against the critical rules, never guess which registry to use, and always ask before switching presets between reinstall, merge, or skip - plus a diff-based safe-update procedure that never overwrites local changes without explicit user approval.

Use it when adding new components from shadcn/ui or community registries, styling, composing, or debugging existing shadcn/ui components, initializing a new project or switching design-system presets, or retrieving component documentation and API references. All CLI commands must run through the project's actual package runner - npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest - rather than a hardcoded one; raw files must never be fetched manually from GitHub when updating a component from upstream, since the CLI's own diff and dry-run tooling is required instead.

Input is a component request - add, style, debug, or update - plus the project's live shadcn context. Output is source-code components added to the project, or a diff-previewed update, following commands like:

npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all

Wraps the shadcn/ui CLI end to end - init, add, search, docs, view, info - across Next.js, Vite, Astro, and other supported templates, Tailwind v3/v4, Radix or "base" primitive libraries, and configurable icon libraries such as lucide-react or @tabler/icons-react. It reads project-specific fields like aliases, isRSC, tailwindVersion, and packageManager to tailor every generated snippet.

Frontend engineers building UI with shadcn/ui who need CLI-correct component addition, project-aware styling conventions, and safe upstream updates rather than hand-rolled markup or guessed import paths.