react-shadcn

为 React SPA（Vite）构建 UI 组件，使用 shadcn/ui（CLI 4.21.0）和 Tailwind CSS v4，并适配项目使用的组件基础：Base UI（自 2026 年 7 月起，新项目的默认选项）、Radix UI（统一的 `radix-ui` 包，完全支持）或 React Aria（2026 年 7 月新增）。涵盖表单（使用 TanStack Form 的 Field/FieldLabel/FieldError 模式，绝不使用 React Hook Form）、覆盖层（Dialog、Sheet、Drawer、Popover、Tooltip）、反馈（Base UI 使用 Alert、Toast；Radix 和 Aria 使用 Sonner，以及 Progress、Skeleton）、数据展示（Table、Badge、Calendar、Chart）和导航（Sidebar、Command、DropdownMenu）。

要求先从 components.json 检测组件基础，再编写任何组件代码；使用 bunx --bun shadcn@latest add 安装组件（绝不手写），并通过 MCP registry 工具（mcp__shadcn__*）在实现前查找组件。这是适用于纯 React 的 shadcn/ui 版本；Next.js App Router 请参阅 nextjs-shadcn。

React 版 shadcn/ui

基于 Base UI、Radix UI 或 React Aria 原语构建的无障碍、可复制到项目中的组件，采用 Tailwind CSS v4 样式。

Agent 工作流（强制）

任何实现开始前，必须并行启动 3 个 Agent，每个调用 Agent 时都要指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有组件和模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 shadcn/ui 文档
3. mcp__shadcn__* - 在 registry 中搜索可用组件

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

适用场景

• 为 React 应用（Vite）构建 UI 组件
• 需要无障碍、可自定义的表单组件（输入框、选择框、复选框）
• 实现对话框、侧边面板、抽屉或覆盖层模式
• 创建支持排序、筛选和分页的数据表格
• 构建导航菜单、侧边栏或命令面板
• 需要 Toast 通知或警告反馈组件

为什么选择 shadcn/ui

特性	优势
复制/粘贴模式	将组件复制到项目中，完全拥有组件
可选基础	Base UI（默认）、Radix UI 或 React Aria——组件名称相同
Tailwind CSS v4 样式	CSS 优先的主题（@theme inline、OKLCH 令牌）
支持 TanStack Form	Field + FieldError 接受 Standard Schema 错误
Lucide 图标（默认）	在 components.json 中通过 iconLibrary 配置，可通过 migrate icons 切换

---

关键规则

1. 先检测组件基础 - 读取 components.json 中的 style：base-* = Base UI，radix-* / new-york = Radix，aria-* = React Aria。单个组件中绝不可混用不同基础
2. 新项目默认使用 Base UI - 除非传入 -b radix / -b aria，否则 init 会选择 Base UI
3. 组合方式遵循组件基础 - Base UI 使用 render={<Button />}；Radix 使用 asChild。在 Base UI 项目中，必须将标记为 Radix 的示例转换后再使用
4. 绝不手动创建组件 - 始终使用 bunx --bun shadcn@latest add 安装（registry 会提供适配项目组件基础的变体）
5. 仅使用 TanStack Form - 不得使用 React Hook Form；在 Field 上设置 data-invalid，并在控件上设置 aria-invalid，以关联错误
6. SOLID 路径 - 组件位于 @/modules/cores/shadcn/components/ui/

---

会改变代码的基础差异

关注点	Base UI（默认）	Radix UI
包	@base-ui/react	radix-ui（统一包；从 @radix-ui/react-* 迁移时使用 migrate radix）
将触发器设为自定义元素	<DialogTrigger render={<Button />}>Open</DialogTrigger>	<DialogTrigger asChild><Button>Open</Button></DialogTrigger>
Select	<Select items={items}>、SelectContent alignItemWithTrigger	<SelectContent position="item-aligned" | "popper">
Accordion	multiple、defaultValue={["item-1"]}	type="single" collapsible / type="multiple"
Toggle group 的值	数组（defaultValue={["bold"]}）、multiple	type="single" | "multiple"
Checkbox 不确定状态	indeterminate 属性	checked="indeterminate"
Drawer	Base UI Drawer（swipeDirection）	Vaul（direction）
Toast	add toast → toast.add({ title })	add sonner → 来自 sonner 的 toast("…")
打开状态样式	data-open / data-closed	data-state="open"（两者都由 shadcn/tailwind.css 中的 data-open: 变体覆盖）

不同基础之间的共通项：组件名称、DialogContent/SheetContent 上的 showCloseButton、 Field 系列、主题令牌。

---

架构

组件基础

• 原语 - Base UI / Radix UI / React Aria（由 components.json 指定）
• Tailwind CSS v4 - 以 CSS 为先的配置：@import "tailwindcss"、@import "shadcn/tailwind.css"、@custom-variant dark、@theme inline
• class-variance-authority - 管理组件样式变体
• cn 包 - 注册表组件使用 import { cn } from "cn"（2026 年 9 月发布，可直接替代 twMerge(clsx(...))）；lib/utils.ts 会重新导出它；使用 shadcn migrate cn 迁移旧项目

项目结构

组件遵循 SOLID 架构，安装到 @/modules/cores/shadcn/components/ui/。工具函数位于 @/modules/cores/lib/utils.ts（export { cn } from "cn"）。

---

MCP 服务集成

运行 bunx --bun shadcn@latest mcp init --client claude（或创建 .mcp.json），即可与 shadcn 注册表集成到 Claude Code。

可用的 MCP 工具

• mcp__shadcn__search_items_in_registries - 搜索可用组件
• mcp__shadcn__view_items_in_registries - 查看组件源代码
• mcp__shadcn__get_item_examples_from_registries - 获取用法示例
• mcp__shadcn__get_add_command_for_items - 获取安装命令

面向 Agent 的 CLI 辅助命令：shadcn info（框架、基础、已安装组件）和 shadcn docs <component> -b <base|radix|aria>。

完整设置说明请参阅 installation.md。

---

组件类别

类别	组件	主要参考
设置	初始化、配置、主题、图标	installation.md
表单	Button、Input、Field、Select、Checkbox、Switch、Slider	field-patterns.md
覆盖层	Dialog、Sheet、Drawer、Popover、Tooltip、HoverCard	dialog.md
反馈	Alert、Toast（Base UI）/ Sonner（Radix、Aria）、Progress、Skeleton、Spinner	toast.md
数据展示	Table、Badge、Avatar、Calendar、Chart、Carousel	table.md
导航	Breadcrumb、DropdownMenu、Command、Sidebar、Tabs	sidebar.md
布局	Card、Accordion、Separator、ScrollArea、Resizable	card.md

除非另有标注，组件参考文档展示的是 Radix API；每篇文档都会在顶部列出 Base UI 的差异。

---

最佳实践

1. 字段组件 - Field + FieldLabel + FieldError errors={field.state.meta.errors}
2. 客户端组件 - React 应用默认在客户端运行（"rsc": false）
3. 按基础组件选择 Toast - 使用 Base UI 时采用 Base UI Toast；使用 Radix/Aria 时采用 Sonner（Radix Toast 已弃用）
4. 优先使用 MCP 工具 - 实现前使用 mcp__shadcn__* 进行探索
5. 通过 CSS 变量设置主题 - 在 src/index.css 的 :root / .dark 中定义 OKLCH 令牌，并通过 @theme inline 暴露
6. 无障碍访问 - 依赖基础组件的键盘导航和 ARIA；在无效控件上保留 aria-invalid

---

参考指南

需求	参考资料
初始设置	installation.md、configuration.md
表单模式	field-patterns.md、form-examples.md
主题自定义	theming.md
数据表格	table.md
模态对话框	dialog.md、alert-dialog.md
导航	sidebar.md、navigation-menu.md