用途
本技能面向使用 shadcn/ui 构建生产级用户界面的开发场景，提供专家级指导，涵盖组件组合、高级模式、注册表编写、主题定制以及与更广泛前端生态的集成。官方文档地址为 https://ui.shadcn.com/docs。
核心理念
shadcn/ui 不是组件库，而是一组设计精美、具备无障碍支持的组件，您将其复制到项目中并拥有它们。其五大支柱为：开放代码（组件位于您的代码库中，完全可编辑）、组合（小型原语组合成复杂 UI）、分发（用于共享组件集的注册表系统）、美观默认（开箱即用、可直接用于生产）、面向 AI（data-slot 属性与结构化 props，便于大语言模型工具使用）。
技能激活场景
在以下情况会激活本技能：向项目添加 shadcn/ui（npx shadcn@latest init）；安装或自定义单个组件（npx shadcn@latest add）；构建复杂模式，如数据表格、带校验表单、侧边栏导航；主题、颜色系统定制与深色模式；创建或消费自定义注册表；从 Tailwind v3 迁移到 v4（配合 shadcn）。
与其他前端技能的协同
本技能与其他前端技能配合使用，并在适当情况下进行路由：需要 CSS 架构、现代 CSS 特性、响应式模式时，路由至 frontend-design；需要页面布局组合、网格系统、断点策略时，路由至 frontend-layout agent；需要动画、微交互、视觉打磨时，路由至 frontend-design agent；需要 UX 流程、设计令牌、组件层级时，路由至 frontend-design agent；需要独特视觉标识、避免通用 AI 美学时，路由至 frontend-css skill；需要 React 19 模式、Server Components、性能时，路由至 react-performance-optimizer agent。本技能负责 shadcn 特定事项：使用哪些组件、如何组合、注册表模式、表单/表格/侧边栏架构以及 shadcn 主题。
实时组件查询
本技能收录了最复杂组件（Data Table、Form、Sidebar、Dialog）的参考模式。对于其他任意组件的 API、props 或用法，可启动 quick-searcher agent 实时抓取文档。所有组件文档遵循可预测的 URL 规则：组件文档为 https://ui.shadcn.com/docs/components/{name}；表单集成为 https://ui.shadcn.com/docs/forms/{library}；Blocks 为 https://ui.shadcn.com/blocks；Registry 为 https://ui.shadcn.com/docs/registry；Themes 为 https://ui.shadcn.com/themes；CLI 参考为 https://ui.shadcn.com/docs/cli；Tailwind v4 为 https://ui.shadcn.com/docs/tailwind-v4；Changelog 为 https://ui.shadcn.com/docs/changelog。
当需要特定组件（如 Combobox、Toast、Sheet）的 API 细节时，可启动 research:quick-searcher agent，并使用给定提示模板抓取对应文档，提取子组件及其 props、必需的无障碍属性、安装命令、关键用法模式与代码示例，返回结构化结果。对于 Radix 原语 API 细节（被 shadcn 继承），抓取 https://www.radix-ui.com/primitives/docs/components/{component-name}；对于 TanStack Table API（被 Data Table 使用），抓取 https://tanstack.com/table/latest/docs/introduction。
组件目录（按类别）
布局：Sidebar、Resizable、Collapsible、Separator、Aspect Ratio。浮层：Dialog、Sheet、Drawer、Alert Dialog、Popover、Tooltip、Hover Card。表单：Input、Textarea、Select、Checkbox、Radio Group、Switch、Slider、Toggle、Toggle Group、Date Picker、Combobox。数据展示：Table、Data Table、Card、Badge、Avatar、Calendar。反馈：Alert、Toast（Sonner）、Progress、Skeleton。导航：Navigation Menu、Breadcrumb、Pagination、Tabs、Command、Menubar、Dropdown Menu、Context Menu。排版：Label、Separator。
安装与设置
新项目：运行 npx shadcn@latest init，选择 New York 风格（默认，default 风格已弃用），选择 Tailwind v4 + React 19（当前默认）。添加组件：npx shadcn@latest add button dialog form sidebar data-table，或添加一个 block：npx shadcn@latest add dashboard-01。CLI v4 功能（2026 年 3 月起）：shadcn add --dry-run dialog 预览更改而不写入；shadcn add --diff dialog 显示将更改的差异；shadcn info 显示已安装组件、框架、CSS 变量；shadcn docs dialog 从 CLI 获取组件文档；shadcn init --template next 使用框架模板初始化脚手架。
组件组合
shadcn 组件是可组合的原语，通过嵌套构建复杂 UI。模式一：子组件组合，如 Dialog 搭配 DialogTrigger、DialogContent、DialogHeader、DialogTitle、DialogDescription。模式二：Slot/asChild 委托，使用 asChild 将渲染委托给子元素，避免额外 DOM 节点，并可使用路由 Link、自定义按钮等。模式三：cn() 工具用于条件类名，从 "@/lib/utils" 导入 cn 并按条件拼接 class。模式四：使用 CVA 变体构建自定义组件，从 class-variance-authority 导入 cva 与 VariantProps，定义 badgeVariants 等。
关键模式
数据表格：采用 TanStack Table 的三文件架构，详见 references/advanced-patterns.md，包含完整列定义、排序、筛选、分页与行选择模式。columns.tsx 为列定义（ColumnDef<TData>[]），data-table.tsx 为带 useReactTable 的表格封装，page.tsx 为用于数据获取的 server component。
表单 + Zod 校验：使用 React Hook Form + Zod resolver，详见 references/advanced-patterns.md，包含字段模式、动态数组与校验模式。使用 useForm<z.infer<typeof schema>> 并配置 resolver: zodResolver(schema) 与默认值。
侧边栏导航：基于 Provider，使用 SidebarProvider，支持 collapsible="icon" 与 collapsible="offcanvas"。详见 references/advanced-patterns.md，包含嵌套导航、移动端响应式与 useSidebar() hook。
主题
颜色系统（Tailwind v4 / OKLCH）：新项目使用 OKLCH 以实现感知颜色一致性，颜色在 globals.css 中定义为 CSS 变量，并通过 @theme inline 映射如 --color-background、--color-foreground、--color-primary、--color-primary-foreground 等。深色模式：通过在 <html> 上切换 class 实现，所有 shadcn 组件自动响应 dark: 变体。定制方式：编辑 globals.css 中的 CSS 变量以进行全局主题更改；使用 cn() 进行单实例覆盖；直接编辑组件源码以进行结构性更改（因为您拥有代码）；使用 data-slot 属性进行定向 CSS 覆盖，避免类名优先级冲突。
Tailwind v4 迁移
参见 references/migration-guide.md 获取从 Tailwind v3 到 v4 的逐步迁移指南，包括 npx @tailwindcss/upgrade@next codemod、动画库替换（tailwindcss-animate 换为 tw-animate-css）、使用 @theme inline 重构 CSS 变量、React 19 中移除 forwardRef、采用 data-slot。
注册表系统
构建并分发您自己的组件集。参见 references/registry-guide.md 了解 registry.json schema 与条目类型、目录结构约定、构建与发布工作流、用于完整设计系统的 registry:base。
常见陷阱
参见 references/pitfalls.md 获取详细问题与修复方案：与自定义配置的 Tailwind 类名冲突、SSR 水合错误（如 Accordion 等）、通配符导入导致的包体积膨胀、无自动更新（需手动运行 shadcn add 刷新组件）、React 19 中 forwardRef 破坏、缺少 ARIA 属性导致的无障碍退化。
社区资源
Blocks：https://ui.shadcn.com/blocks 为官方可组合页面区块；shadcnblocks.com 提供 1100+ 社区区块与模板；registry.directory 为第三方注册表浏览器；shadcn-admin（GitHub，6k+ stars）为完整管理后台起步模板；next-forge（GitHub，6.9k+ stars）为包含支付、分析、国际化的 Turborepo monorepo。
Server 与 Client 组件
数据获取页面使用 Server Components（Next.js App Router 中的默认值）；交互组件（Dialog、Form、DataTable）使用 "use client"；列定义使用 "use client"（因引用 React 组件）；布局外壳、路由段优先使用 Server Components；将 "use client" 边界尽可能放在组件树较低位置。