用 shadcn/ui 构建可定制 React…

在 React + Tailwind 项目中集成、定制和维护 shadcn/ui 组件（含 MCP 工具发现、CLI 安装、主题与变体定制、可访问性保障与故障排查）。

适用场景

解决思路

1. 用 shadcn MCP 工具浏览组件目录与 Registry Directory：用 `list_components` 列出全部组件，用 `get_component_metadata` 查看 props、依赖与用法，用 `get_component_demo` 查看实现示例。
2. 优先用直接安装方式添加组件：执行 `npx shadcn@latest add [component-name]`，它会下载组件源码（按配置适配 Radix 或 Base UI）、安装所需依赖、把文件放到 `components/ui/` 并更新 `components.json`。
3. 需要手动集成时：用 `get_component` 获取源码，在 `components/ui/[component-name].tsx` 创建文件，手动安装 peer 依赖，必要时调整 import。
4. 使用自定义 registry（在 `components.json` 中定义）或浏览 Registry Directory 时：用 `get_project_registries` 列出可用 registry，用 `list_items_in_registries` 查看其中的组件，用 `view_items_in_registries` 获取详细信息，用 `search_items_in_registries` 搜索特定组件。
5. 新项目用 `npx shadcn@latest create` 定制风格、字体与组件库；已有项目用 `npx shadcn@latest init` 初始化配置。
6. 在 `components.json` 中配置：style（default、new-york，或 Vega、Nova、Maia、Lyra、Mira 等新视觉风格）、baseColor（slate、gray、zinc、neutral、stone）、cssVariables（是否用 CSS 变量）、tailwind config 路径、aliases 导入路径别名、rsc（是否用 React Server Components）、rtl（可选，启用 RTL 支持）。
7. 确保依赖齐全：React 18+、Tailwind CSS 3.0+、Radix UI 或 Base UI 原语、class-variance-authority（变体样式）、clsx 与 tailwind-merge（类名组合）。
8. 按推荐结构组织文件：`src/components/ui/` 放 shadcn 组件，`src/components/[custom]/` 放自己组合的组件，`src/lib/utils.ts` 放 `cn()` 工具，`src/app/` 放页面。
9. 用 `cn()` 工具合并类名：基于 `clsx` 与 `tailwind-merge` 实现，用于无冲突地覆盖默认样式、条件应用类名、智能合并 Tailwind 类。
10. 主题定制：在 Tailwind 配置与 `app/globals.css` 中编辑 CSS 变量，在 `:root` 定义亮色变量、在 `.dark` 定义暗色覆盖。
11. 用 `class-variance-authority`（cva）定义组件变体逻辑，声明 variants（如 variant、size）与 defaultVariants。
12. 扩展组件时在 `components/`（而非 `components/ui/`）中创建包装组件，例如基于 `Button` 封装带 loading 状态的 `LoadingButton`。
13. 使用 shadcn/ui 提供的完整 UI blocks（认证表单、仪表盘等）：用 `list_blocks`（可带分类过滤）列出，用 `get_block` 获取源码，安装时注意许多 block 包含多个组件文件；分类包括 calendar、dashboard、login、sidebar、products。
14. 定制时保持可访问性：保留 ARIA 属性、保留键盘处理逻辑、用屏幕阅读器测试、保留焦点指示器。
15. 常见模式：表单用 `Button`/`Input`/`Label` 配合 react-hook-form 做校验；弹窗用 `Dialog`、`DialogContent`、`DialogDescription`、`DialogHeader`、`DialogTitle`、`DialogTrigger`；数据展示用 `Table`、`TableBody`、`TableCell`、`TableHead`、`TableHeader`、`TableRow`。
16. 排查 import 错误：检查 `components.json` 的 alias 配置，确认 `tsconfig.json` 包含 `@` 路径别名（`"@/*": ["./src/*"]`）。
17. 排查样式冲突：确认 Tailwind CSS 配置正确、根布局已导入 `globals.css`、组件与主题的 CSS 变量名一致。
18. 排查缺失依赖：用 CLI 安装组件以自动装依赖，手动检查 `package.json` 中的 Radix UI 包，用 `get_component_metadata` 查看依赖列表。
19. 排查版本兼容：shadcn/ui v4 需要 React 18+ 与 Next.js 13+（若用 Next.js），部分组件需要特定 Radix UI 版本，查阅文档了解版本间的破坏性变更。
20. 提交组件前做质量校验：运行 `tsc --noEmit` 做类型检查、运行 linter、用 axe DevTools 等工具测试可访问性、在亮暗两种模式下做视觉检查、在不同断点验证响应式表现。
21. 参考资源文件获取详细指导：`resources/setup-guide.md`（项目初始化）、`resources/component-catalog.md`（组件参考）、`resources/customization-guide.md`（主题与变体）、`resources/migration-guide.md`（从其他 UI 库升级）；`examples/` 目录含完整实现、表单校验模式、仪表盘布局、认证流程与数据表实现。

适用边界 · 注意事项

• 项目不使用 React 18+ 或 Tailwind CSS 3.0+ 时（shadcn/ui 依赖这两者）。
• 需要传统 npm 包式组件库（版本锁定、从 node_modules 引入）而非把源码复制进代码库时。
• 无法使用 shadcn CLI 或 MCP 工具、且不愿手动复制源码与安装 peer 依赖时。