---

name: shadcn description: 管理 shadcn/ui 组件和项目，提供构建现代设计系统的上下文、文档和使用模式。 user-invocable: false risk: safe source: https://github.com/shadcn-ui/ui/tree/main/skills/shadcn date_added: "2026-03-07"

shadcn/ui

一个用于构建 UI、组件和设计系统的框架。组件通过 CLI 作为源代码添加到用户项目中。

重要： 使用项目的包运行器运行所有 CLI 命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest——根据项目的 packageManager 选择。以下示例使用 npx shadcn@latest，但请替换为项目的正确运行器。

何时使用

• 从 shadcn/ui 或社区注册表添加新组件时使用。
• 为现有 shadcn/ui 组件设置样式、组合或调试时使用。
• 初始化新项目或切换设计系统预设时使用。
• 检索组件文档、示例和 API 参考时使用。

当前项目上下文

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

上面的 JSON 包含项目配置和已安装的组件。使用 npx shadcn@latest docs <component> 获取任何组件的文档和示例 URL。

原则

1. 优先使用现有组件。 在编写自定义 UI 之前，使用 npx shadcn@latest search 检查注册表。也检查社区注册表。
2. 组合，不要重新发明。 设置页面 = Tabs + Card + 表单控件。仪表板 = Sidebar + Card + Chart + Table。
3. 优先使用内置变体而非自定义样式。 variant="outline"、size="sm" 等。
4. 使用语义化颜色。 bg-primary、text-muted-foreground——永远不要使用原始值如 bg-blue-500。

关键规则

这些规则始终强制执行。每条规则链接到包含错误/正确代码对比的文件。

样式和 Tailwind → styling.md

• className 用于布局，不用于样式。 永远不要覆盖组件颜色或排版。
• 不使用 space-x-* 或 space-y-*。 使用 flex 配合 gap-*。垂直堆叠使用 flex flex-col gap-*。
• 宽高相等时使用 size-*。 用 size-10 而非 w-10 h-10。
• 使用 truncate 简写。 而非 overflow-hidden text-ellipsis whitespace-nowrap。
• 不手动使用 dark: 颜色覆盖。 使用语义化 token（bg-background、text-muted-foreground）。
• 使用 cn() 处理条件类名。 不要编写手动模板字面量三元表达式。
• 不在覆盖层组件上手动设置 z-index。 Dialog、Sheet、Popover 等自行处理堆叠顺序。

表单和输入 → forms.md

• 表单使用 FieldGroup + Field。 永远不要使用原始 div 配合 space-y-* 或 grid gap-* 进行表单布局。
• InputGroup 使用 InputGroupInput/InputGroupTextarea。 永远不要在 InputGroup 内使用原始 Input/Textarea。
• 输入框内的按钮使用 InputGroup + InputGroupAddon。
• 选项集（2-7 个选择）使用 ToggleGroup。 不要循环 Button 并手动管理激活状态。
• 使用 FieldSet + FieldLegend 分组相关的复选框/单选框。 不要使用带标题的 div。
• 字段验证使用 data-invalid + aria-invalid。 Field 上使用 data-invalid，控件上使用 aria-invalid。禁用状态：Field 上使用 data-disabled，控件上使用 disabled。

组件结构 → composition.md

• Item 始终在其 Group 内。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 使用 asChild（radix）或 render（base）自定义触发器。 检查 npx shadcn@latest info 中的 base 字段。→ base-vs-radix.md
• Dialog、Sheet 和 Drawer 始终需要 Title。 DialogTitle、SheetTitle、DrawerTitle 是无障碍所必需的。视觉隐藏时使用 className="sr-only"。
• 使用完整的 Card 组合。 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要把所有内容都放在 CardContent 中。
• Button 没有 isPending/isLoading。 使用 Spinner + data-icon + disabled 组合。
• TabsTrigger 必须在 TabsList 内。 永远不要直接在 Tabs 中渲染触发器。
• Avatar 始终需要 AvatarFallback。 用于图片加载失败时的回退。

使用组件，而非自定义标记 → composition.md

• 优先使用现有组件而非自定义标记。 在编写样式化 div 之前检查组件是否存在。
• 提示框使用 Alert。 不要构建自定义样式 div。
• 空状态使用 Empty。 不要构建自定义空状态标记。
• Toast 通过 sonner。 使用 sonner 中的 toast()。
• 使用 Separator 代替 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作为加载占位符。不要使用自定义 animate-pulse div。
• 使用 Badge 代替自定义样式 span。

图标 → icons.md

• Button 中的图标使用 data-icon 属性。