用途：shadcn/ui 不是 npm 依赖，而是代码生成平台。它通过 CLI 把组件源码复制到你的项目中，组件归你所有，可自由修改。适用于添加组件、用 CSS 变量与 oklch 颜色做主题、构建表单、创建自定义注册表、组合可访问的组件变体以及设置暗色模式。
主要能力：支持 Radix UI 或 Base UI 原语、Tailwind CSS 4 与 oklch 颜色令牌、React 19 直接 ref 模式（forwardRef 已弃用）、Field 组件配合 React Hook Form 或 TanStack Form 与 Zod 做类型安全校验。主题令牌用 :root 变量加 @theme inline 映射，暗色模式通过 .dark 类切换。组件变体用 class-variance-authority 的 cva()，多态插槽用 asChild 与 Radix 的 Slot，类名合并用 cn() 包装 clsx 与 twMerge。通知默认使用 Sonner。
使用方式：初始化项目运行 npx shadcn@latest init；添加组件运行 npx shadcn@latest add [name]；自定义项目运行 npx shadcn@latest create；检查上游更新运行 npx shadcn@latest diff [component]；搜索注册表运行 npx shadcn@latest search @registry；构建注册表运行 npx shadcn@latest build。可用 npx shadcn@latest init sidebar-01 以预置区块引导项目。RTL 支持在根元素设置 dir="rtl"。
适用场景：React 项目中使用 Tailwind CSS 并希望拥有组件源码、需要可访问性与主题定制的场景。
限制：不适用于非 React 框架（应改用 shadcn-vue 或 shadcn-svelte）、使用其他组件库（如 MUI、Chakra）的项目，以及未使用 Tailwind CSS 的项目。新表单应使用 Field 组件而非旧版 Form；颜色令牌应使用 oklch 而非 HSL；不要将 shadcn/ui 作为 npm 依赖安装，也不要修改 node_modules 中的组件。旧命令 shadcn-ui@canary 应替换为 npx shadcn@latest。