用途：shadcn/ui 不是传统组件库，而是一套构建自有组件库的系统。组件以开源代码复制进项目，开发者完全拥有并可修改。提供 Base UI（MUI 出品）与 Radix UI（默认）两种原语变体。本指南用于安装、配置、主题化与使用 shadcn/ui 组件，不适用于 Chakra UI、MUI、Ant Design 或无 shadcn/ui 上下文的原生 Tailwind CSS。
主要能力：CLI 提供 create（交互式脚手架）、init（初始化配置）、add（添加组件，支持 --all）、view、search/list、build、migrate、mcp 等命令，常用标志有 -y、-o、-a、-c、-s。配置位于项目根目录 components.json，schema 为 https://ui.shadcn.com/schema.json；style、baseColor、cssVariables 在 init 后不可更改，默认使用 new-york 风格。主题使用 OKLCH 颜色与 CSS 变量，约定 --[role] 为背景、--[role]-foreground 为文字，基础色有 neutral、stone、zinc、gray、slate。共 58 个组件，覆盖浮层、导航、表单输入、表单控件、数据展示、布局与反馈等类别。
使用方式：初始化 npx shadcn@latest init；添加组件 npx shadcn@latest add button dialog card；添加全部 npx shadcn@latest add --all；交互式创建 npx shadcn@latest create。组件导入路径为 @/components/ui/[component]。工具函数 cn 由 init 生成于 lib/utils.ts。暗色模式可用 next-themes（Next.js）、remix-themes（Remix）或自定义 context。表单可用 React Hook Form + zod 或 TanStack Form，配合 Field 组件。注册表支持分发自定义组件，构建后服务于 /r/[name].json，安装如 npx shadcn@latest add @acme/button。
适用场景：Next.js、Vite、Astro、React Router、Remix、Laravel、Gatsby、TanStack Start/Router 等框架项目，以及 monorepo（需在 apps/web 运行 CLI）。
限制：style、baseColor、cssVariables 初始化后不可变；Toast 已弃用，改用 Sonner；默认风格已弃用；Tailwind v4 使用 @theme inline，tailwind.config 留空，动画库改用 tw-animate-css；React 19 不再使用 forwardRef；npm 与 React 19 可能需 --force 或 --legacy-peer-deps；非 Next.js 项目需设 rsc: false；JavaScript 项目设 "tsx": false 并使用 jsconfig.json；Tailwind v3 旧文档见 v3.shadcn.com。社区注册表由第三方维护，安装前应审查代码。