技能介绍

要解决的问题

在 React + shadcn/ui 项目里，主题基础设施（CSS 变量、components.json、cn() 工具）搭好之后，真正开始组装界面时，工程师经常要面对几个具体问题：组件应该先装哪些再装哪些；表单、反馈、浮层、数据展示和导航各自依赖哪些外部库；以及 Radix、React Hook Form、Lucide、Dialog 在实际使用中的边界情况。手动拼装时，很容易在 Select 的空字符串 value、Input 拒绝 null、图标被 tree-shake、Dialog 宽度覆盖断点不一致等细节上反复调试，也容易漏掉 react-hook-form、zod、sonner、cmdk、@tanstack/react-table 这类外部依赖。

技能如何工作

该技能以 shadcn/ui 组件工程师的角色工作，接受已搭好主题的项目，也可以接收 ProjectPath。它把组件装配拆成四个步骤：

按依赖顺序安装：先装基础组件（button、input、label、card），再装功能组件。表单需要 react-hook-form、zod 与 @hookform/resolvers；toast 需要 sonner；浮层包括 dialog、sheet、popover、dropdown-menu；数据表需要 @tanstack/react-table；导航里的 command 需要 cmdk。外部依赖单独安装。
避坑：Radix Select 不要用空字符串 value，改用哨兵值如 __any__；React Hook Form 不要直接展开 {...field}，Input 不接受 null，应写 field.value ?? ''；Lucide 图标要显式具名引入，避免生产环境被 tree-shake 掉；Dialog 的宽度覆盖要使用相同断点前缀，例如 sm:max-w-6xl，否则覆盖不会生效。
定制：颜色使用语义 token 而不是裸色，例如 bg-primary 而不是 bg-blue-500；变体扩展直接编辑 src/components/ui/ 下的组件文件，增加 cva 变体。
组合配方：联系表单（Form + Input + Textarea + Button + Toast）、数据表（Table + 排序 + 分页 + 搜索）、弹窗 CRUD（Dialog + Form + Button）、导航（Sheet + NavigationMenu + ModeToggle）、设置页（Tabs + Form + Switch + Select + Toast）。

技能最终输出一份 ComponentPlan，包含 foundation、feature、external_deps 和 recipes。它上游依赖 tailwind-theme-builder，下游可交给 design-review。输出内容为安装清单（含外部依赖）与定制、配方建议，完整组件目录和外部依赖表存放在 references/template.md。

适用边界与注意点

该技能的前提是项目已经搭好主题基础设施：CSS 变量、components.json、cn() 工具必须存在。如果这些还没有，应先运行 tailwind-theme-builder。它不适用于非 React 或非 shadcn/ui 的项目，也不负责主题初始化本身。输出物是计划和建议，不是最终组件代码；落地时仍需结合项目现有的目录结构和类型定义执行。