用途
shadcn/ui 是一个用于构建 UI、组件和设计系统的框架，组件以源代码形式通过 CLI 添加到用户项目中。本技能用于管理 shadcn 组件与项目，包括添加、搜索、修复、调试、样式设置和组合 UI，也涵盖聊天界面。
主要能力
- 提供项目上下文信息，包括项目配置与已安装组件，通过
npx shadcn@latest info --json获取。 - 通过
npx shadcn@latest docs <component>获取组件的文档与示例 URL。 - 通过
npx shadcn@latest search搜索注册表中的组件。 - 通过
npx shadcn@latest add添加或更新组件。 - 支持预设（preset）相关操作：
preset decode、preset url、preset open、preset resolve、apply、init --preset。
使用方式
所有 CLI 命令需使用项目的包管理器运行：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。
常用命令示例：
# 创建新项目
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite
# 创建设计系统应用
npx shadcn@latest init --name my-ds --preset b0 --template vite --no-monorepo -y
npx shadcn@latest init --name my-ds --base base --preset maia --template vite --no-monorepo -y
npx shadcn@latest add --all -y
# 创建 monorepo 项目
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
# 初始化已有项目
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults
# 应用预设到已有项目
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply a2r6bw --only theme
npx shadcn@latest apply a2r6bw --only font
npx shadcn@latest apply a2r6bw --only theme,font
# 检查预设代码与项目预设状态
npx shadcn@latest preset decode a2r6bw
npx shadcn@latest preset url a2r6bw
npx shadcn@latest preset open a2r6bw
npx shadcn@latest preset resolve
npx shadcn@latest preset resolve --json
# 添加组件
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add owner/repo/item
npx shadcn@latest add --all
# 添加/更新前预览变更
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx
npx shadcn@latest add owner/repo/item --dry-run
# 搜索注册表
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"
npx shadcn@latest search owner/repo -q "login"
npx shadcn@latest search
npx shadcn@latest search @shadcn -q "menu" -t ui
工作流程
- 获取项目上下文。
- 先检查已安装组件，避免导入未添加的组件或重复添加。
- 查找组件（
search）。 - 获取文档与示例（
docs，然后用view浏览未安装的注册表项，用add --diff预览已安装组件的变更）。 - 安装或更新（
add，更新时先用--dry-run和--diff预览）。 - 修复第三方组件的导入（社区注册表组件可能使用不匹配的硬编码路径）。
- 审查已添加的组件，检查缺失子组件、缺失导入、错误组合或违反关键规则，并按项目图标库替换图标导入。
关键规则摘要
- 样式与 Tailwind：className 用于布局而非样式；不使用
space-x-*/space-y-*，改用flex与gap-*；等宽高用size-*；截断用truncate；不使用手动dark:覆盖，使用语义化 token；条件类使用cn()；覆盖层组件不手动设置 z-index。 - 表单与输入：使用 FieldGroup + Field；InputGroup 内使用 InputGroupInput/InputGroupTextarea；按钮在输入框内使用 InputGroup + InputGroupAddon；2–7 个选项用 ToggleGroup；校验用
data-invalid与aria-invalid。 - 组件结构：Item 始终放在其 Group 内；自定义触发用 asChild（radix）或 render（base）；Dialog、Sheet、Drawer 必须有 Title；使用完整 Card 组合；Button 无 isPending/isLoading，用 Spinner + data-icon + disabled 组合；TabsTrigger 必须在 TabsList 内；Avatar 始终需要 AvatarFallback。
- 使用组件而非自定义标记：提示用 Alert；空状态用 Empty；Toast 依项目基础选择；分隔用 Separator；加载占位用 Skeleton；徽章用 Badge。
- 图标：Button 中图标用
data-icon；组件内图标不加尺寸类；图标以对象传入而非字符串键。 - 聊天与消息：使用 MessageScroller、Message、Bubble、Attachment、Marker 等原语。
组件选择参考
按需求选择：按钮/操作用 Button；表单输入用 Input、Select、Combobox、Switch、Checkbox、RadioGroup、Textarea、InputOTP、Slider；切换 2–5 个选项用 ToggleGroup；数据展示用 Table、Card、Badge、Avatar；导航用 Sidebar、NavigationMenu、Breadcrumb、Tabs、Pagination；覆盖层用 Dialog、Sheet、Drawer、AlertDialog；反馈用 toast、sonner、Alert、Progress、Skeleton、Spinner；命令面板用 Dialog 内的 Command；图表用 Chart；布局用 Card、Separator、Resizable、ScrollArea、Accordion、Collapsible；空状态用 Empty；菜单用 DropdownMenu、ContextMenu、Menubar；提示/信息用 Tooltip、HoverCard、Popover；聊天/对话 UI 用 MessageScroller、Message、Bubble、Attachment、Marker。
适用于设计系统
当用户要求基于 DESIGN.md（或品牌规范）构建设计系统时，按 design-system.md 端到端执行，包括初始化、读取 DESIGN.md、映射 token、重设组件样式、构建设计系统页面并在浏览器中验证。
限制
- 不得猜测注册表，若用户未指定注册表需询问。
- 未经用户明确批准不得使用
--overwrite。 - 绝不手动从 GitHub 获取原始文件，始终使用 CLI。
- 预设命令必须在用户项目目录内运行；
apply仅适用于已有components.json的项目。 - 未提供收费、价格信息。