shadcn-ui

shadcn/ui 组件

为已配置主题的 React 项目添加 shadcn/ui 组件。本 Skill 会在 tailwind-theme-builder 完成 CSS 变量、ThemeProvider 和暗黑模式设置之后运行。主要负责组件的安装、自定义以及将多个组件组合成可直接使用的 UI 范式。

前置条件：必须先建立主题基础设施（CSS 变量、components.json、cn() 工具函数）。如果尚未配置，请先使用 tailwind-theme-builder。

安装顺序

按照依赖顺序安装组件。先安装基础组件，再安装功能组件：

基础组件（优先安装）

pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add input label
pnpm dlx shadcn@latest add card

功能组件（按需安装）

# 表单组件
pnpm dlx shadcn@latest add form        # 需要：react-hook-form, zod, @hookform/resolvers
pnpm dlx shadcn@latest add textarea select checkbox switch

# 反馈组件
pnpm dlx shadcn@latest add toast        # 需要：sonner
pnpm dlx shadcn@latest add alert badge

# 浮层组件
pnpm dlx shadcn@latest add dialog sheet popover dropdown-menu

# 数据展示组件
pnpm dlx shadcn@latest add table        # 数据表格，还需：@tanstack/react-table
pnpm dlx shadcn@latest add tabs separator avatar

# 导航组件
pnpm dlx shadcn@latest add navigation-menu command

外部依赖

组件	依赖项
Form	react-hook-form, zod, @hookform/resolvers
Toast	sonner
Data Table	@tanstack/react-table
Command	cmdk
Date Picker	date-fns（可选）

单独安装外部依赖：pnpm add react-hook-form zod @hookform/resolvers

常见踩坑点（Gotchas）

以下是官方/实战整理避坑指南，可防止常见 Bug：

Radix Select —— 不能传空字符串

// 切勿使用空字符串值
<SelectItem value="">All</SelectItem>           // 报错/异常

// 使用哨兵值（Sentinel value）
<SelectItem value="__any__">All</SelectItem>    // 正常工作
const actual = value === "__any__" ? "" : value

React Hook Form —— Null 值处理

// 不要直接展开 {...field} —— 它会传递 null 导致 Input 报错
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

Lucide Icons —— Tree-Shaking 踩坑

// 不要使用动态属性索引 —— 生产环境编译时图标会被摇掉（Tree-shaken）
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // 生产环境失效

// 改用显式 Map 映射
import { Home, Users, Settings, type LucideIcon } from 'lucide-react'
const ICON_MAP: Record<string, LucideIcon> = { Home, Users, Settings }
const Icon = ICON_MAP[iconName]

Dialog 宽度覆盖问题

// 默认的 sm:max-w-lg 不会被 max-w-6xl 覆盖
<DialogContent className="max-w-6xl">       // 生效失败

// 使用相同的响应式断点前缀
<DialogContent className="sm:max-w-6xl">    // 生效成功

自定义组件

shadcn 组件使用的是主题中定义的语义化 CSS Token。按以下方式自定义：

扩展 Variant 变体

编辑 src/components/ui/ 中的组件源码文件来添加自定义变体：

// button.tsx — 添加 "brand" 变体
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... 原有变体
    },
  },
})

颜色覆盖

务必使用主题中的语义化 Token，绝对不要硬编码 Tailwind 色值：

// 不要使用硬编码颜色
<Button className="bg-blue-500">             // 错误

// 使用语义化 Token
<Button className="bg-primary">              // 正确
<Card className="bg-card text-card-foreground">  // 正确

工作流

步骤 1：梳理项目需求

确定项目需要哪些 UI 模式：

场景需求	对应组件
带校验的表单	Form, Input, Label, Select, Textarea, Button, Toast
支持排序的数据展示	Table, Badge, Pagination
后台增删改查（CRUD）界面	Dialog, Form, Table, Button, Toast
营销 / 落地页（Landing Page）	Card, Button, Badge, Separator
设置 / 偏好配置页	Tabs, Form, Switch, Select, Toast
导航栏	NavigationMenu (桌面端), Sheet (移动端), ModeToggle

步骤 2：安装所需组件

先安装基础组件，再根据梳理出的需求安装对应的功能组件。具体安装命令见上文。

步骤 3：组合 UI 范式（Recipes）

将基础组件拼装组合为可直接运行的完整模式。参阅 references/recipes.md 查看完整的示例代码：

• 联系表单 — Form + Input + Textarea + Button + Toast
• 数据表格 — Table + 列排序 + 分页 + 搜索
• 弹窗增删改查 — Dialog + Form + Button
• 导航栏 — Sheet + NavigationMenu + ModeToggle
• 设置页面 — Tabs + Form + Switch + Select + Toast

步骤 4：个性化自定义

利用主题中的语义化 Token，配置项目特有的颜色与样式变体。

参考文档

场景	参考文档
挑选组件、查看安装命令和 Props	references/component-catalogue.md
搭建完整的 UI 模式	references/recipes.md