shadcn-ui

shadcn/ui

概览

介绍如何将 shadcn/ui 用作代码生成平台（而非 npm 依赖项）来构建易于访问且可自定义的 UI。组件通过 CLI 复制到你的项目中，并完全由你掌控。支持 Radix UI 或 Base UI 基元、带有 oklch 颜色令牌的 Tailwind CSS 4、React 19 直接 ref 模式，以及使用 Field 组件和 Zod 进行类型安全的表单验证。

适用场景： 添加 shadcn/ui 组件，使用 CSS 变量和 oklch 颜色设置主题，使用 React Hook Form 或 TanStack Form 构建表单，创建自定义注册表，组合易于访问的组件变体，设置深色模式。

不适用场景： 非 React 框架（请改用 shadcn-vue 或 shadcn-svelte）、使用其他组件库（MUI、Chakra）的项目、未使用 Tailwind CSS 的项目。

快速参考

模式	API / 方式	关键要点
初始化项目	npx shadcn@latest init	自动检测框架，配置 CSS 变量
添加组件	npx shadcn@latest add [name]	将源代码复制到你的项目中
自定义项目	npx shadcn@latest create	选择库（Radix/Base UI）、样式、主题和字体
检查更新	npx shadcn@latest diff [component]	显示组件的上游更改
搜索注册表	npx shadcn@latest search @registry	浏览并从带命名空间的注册表安装
构建注册表	npx shadcn@latest build	根据 registry.json 生成注册表 JSON
主题令牌	:root vars + @theme inline 映射	oklch 颜色值，通过 .dark 类实现深色模式
深色模式	@custom-variant dark (&:is(.dark *))	在 .dark 选择器下切换 CSS 变量
组件变体	来自 class-variance-authority 的 cva()	类型安全的变体定义
多态插槽	使用 Radix 的 <Slot> 配合 asChild 属性	将属性合并到子元素上
直接 ref	将 ref 作为常规属性	forwardRef 在 React 19 中已弃用
表单（当前）	<Field /> + React Hook Form + Zod	替代旧版 <Form /> 组件
表单（旧版）	<Form /> + <FormField /> + Zod	仍可使用，但不再积极开发
合并类名	封装 clsx + twMerge 的 cn() 工具	安全合并 Tailwind 类，避免冲突
Toast / 通知	Sonner（npx shadcn@latest add sonner）	默认通知方案；自动关闭、堆叠
使用区块初始化	npx shadcn@latest init sidebar-01	使用预构建的页面区块引导项目
RTL 支持	在根元素上设置 dir="rtl"	所有组件均内置 RTL 布局支持
新组件	Spinner、Kbd、ButtonGroup	最近新增的实用和布局组件

常见错误

错误	正确做法
将 shadcn/ui 安装为 npm 依赖	使用 CLI（npx shadcn@latest add）将源代码复制到项目中
在 React 19 组件中使用 forwardRef	直接将 ref 作为 prop 传递——forwardRef 在 React 19 中已弃用
使用 HSL 值作为颜色令牌	使用 oklch 格式：--primary: oklch(0.205 0 0)
在实用类中用 hsl() 或 oklch() 包装变量	直接引用 CSS 变量：var(--primary)
将令牌直接放在 @theme {} 中	使用 :root 设置值，再用 @theme inline 将它们映射到 Tailwind
在新表单中使用旧版 <Form />	使用 <Field /> 组件搭配 React Hook Form 或 TanStack Form
跳过表单组件中的 Zod 验证	始终为表单配套使用 Zod 模式，以进行类型安全的验证
使用 div 元素作为交互控件	使用 Radix 或 Base UI 原语，实现语义化 HTML 和无障碍访问
修改 node_modules 中的组件	组件位于源代码树中——直接管理并自定义它们
使用旧版 CLI 命令 shadcn-ui@canary	所有 CLI 操作均使用 npx shadcn@latest

委派

• 组件发现和原语查找：使用 Explore Agent
• 主题迁移或多文件重构：使用 Task Agent
• 设计系统架构规划：使用 Plan Agent
• Registry 设置和分发：使用 Task Agent

如果有 tanstack-form skill，请将高级表单状态管理（数组字段、关联字段、异步验证）委派给它。 如果有 tailwind skill，请将实用类模式和设计令牌架构委派给它。

参考资料

• 主题和深色模式
• 组件模式和变体
• 使用 Field、React Hook Form 和 Zod 的表单模式
• CLI 和 registry