nextjs-shadcn

使用 shadcn/ui（CLI 4.21.0）和 Tailwind CSS v4，为 Next.js App Router 构建 UI 组件，适配项目所用的任意组件基础库——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 将组件安装到 @/modules/cores/shadcn/components/ui/（绝不手写）；并涵盖 MCP 注册表工具（mcp__shadcn__*），以便在实现前发现组件。这是适用于 Next.js App Router 的 shadcn/ui 版本——普通 React/Vite 应用请参阅 react-shadcn。

Next.js 版 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__* - 搜索注册表，查找可用组件

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

---

概览

适用场景

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

选择 shadcn/ui 的原因

功能	优势
复制/粘贴模式	组件会复制到你的项目中，完全归你所有
基础库可选	Base UI（默认）、Radix UI 或 React Aria——组件名称相同
Tailwind CSS v4 样式	CSS 优先的主题（@theme inline、OKLCH 令牌）
支持 TanStack Form	Field + FieldError 可接收 Standard Schema 错误
服务端组件	"rsc": true——CLI 仅在需要时添加 "use client"
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。标记为 Radix 的示例在 Base UI 项目中必须转换
4. 绝不要手动创建组件 - 始终使用 bunx --bun shadcn@latest add 安装（注册表会提供适配项目基础库的变体）
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 组件 - Field + FieldLabel + FieldError errors={field.state.meta.errors}
2. 默认使用服务端组件 - 仅在需要交互性时添加 "use client"；表单也可以使用 Server Actions + useActionState，并采用相同的 Field 模式
3. 按基础组件选择 Toast - Base UI 使用 Base UI Toast；Radix/Aria 使用 Sonner（Radix Toast 已弃用）
4. 优先使用 MCP 工具 - 实现前先使用 mcp__shadcn__* 进行探索
5. 通过 CSS 变量设置主题 - 在 app/globals.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