shadcn-ui

shadcn/ui 组件

为使用主题的 React 项目添加 shadcn/ui 组件。此技能会在 tailwind-theme-builder 设置好 CSS 变量、ThemeProvider 和深色模式后运行。它负责安装和自定义组件，并将组件组合为可用的模式。

前置条件：主题基础设施必须已就绪（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

功能组件（按需安装）

# Forms
pnpm dlx shadcn@latest add form        # needs: react-hook-form, zod, @hookform/resolvers
pnpm dlx shadcn@latest add textarea select checkbox switch

# Feedback
pnpm dlx shadcn@latest add toast        # needs: sonner
pnpm dlx shadcn@latest add alert badge

# Overlay
pnpm dlx shadcn@latest add dialog sheet popover dropdown-menu

# Data Display
pnpm dlx shadcn@latest add table        # for data tables, also: @tanstack/react-table
pnpm dlx shadcn@latest add tabs separator avatar

# Navigation
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

已知注意事项

以下为已记录的修正，可避免常见错误：

Radix Select — 不允许空字符串

// Don't use empty string values
<SelectItem value="">All</SelectItem>           // BREAKS

// Use sentinel value
<SelectItem value="__any__">All</SelectItem>    // WORKS
const actual = value === "__any__" ? "" : value

React Hook Form — Null 值

// Don't spread {...field} — it passes null which Input rejects
<Input
  value={field.value ?? ''}
  onChange={field.onChange}
  onBlur={field.onBlur}
  name={field.name}
  ref={field.ref}
/>

Lucide 图标 — Tree-Shaking

// Don't use dynamic import — icons get tree-shaken in production
import * as LucideIcons from 'lucide-react'
const Icon = LucideIcons[iconName]  // BREAKS in prod

// Use explicit 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 宽度

// Default sm:max-w-lg won't be overridden by max-w-6xl
<DialogContent className="max-w-6xl">       // DOESN'T WORK

// Use same breakpoint prefix
<DialogContent className="sm:max-w-6xl">    // WORKS

自定义组件

shadcn 组件使用主题中的语义 CSS 令牌。自定义方法如下：

扩展变体

通过编辑 src/components/ui/ 中的组件文件添加自定义变体：

// button.tsx — add a "brand" variant
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      brand: "bg-brand text-brand-foreground hover:bg-brand/90",
      // ... existing variants
    },
  },
})

颜色覆盖

使用主题中的语义令牌，切勿使用原始 Tailwind 颜色：

// Don't use raw colours
<Button className="bg-blue-500">             // WRONG

// Use semantic tokens
<Button className="bg-primary">              // RIGHT
<Card className="bg-card text-card-foreground">  // RIGHT

工作流

步骤 1：评估需求

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

需求	组件
带验证的表单	Form、Input、Label、Select、Textarea、Button、Toast
带排序的数据展示	Table、Badge、Pagination
管理后台 CRUD 界面	Dialog、Form、Table、Button、Toast
营销／落地页	Card、Button、Badge、Separator
设置／偏好选项	Tabs、Form、Switch、Select、Toast
导航	NavigationMenu（桌面端）、Sheet（移动端）、ModeToggle

步骤 2：安装组件

先安装基础组件，再根据已确定的需求安装功能组件。使用上方的命令。

步骤 3：构建示例模式

将组件组合为可用的模式。完整示例请参阅 references/recipes.md：

• 联系表单 — Form + Input + Textarea + Button + Toast
• 数据表格 — Table + 列排序 + Pagination + 搜索
• 模态 CRUD — Dialog + Form + Button
• 导航 — Sheet + NavigationMenu + ModeToggle
• 设置页面 — Tabs + Form + Switch + Select + Toast

步骤 4：自定义

使用主题中的语义令牌应用项目专属的颜色和变体。

参考文件

适用场景	阅读
选择组件、安装命令、属性	references/component-catalogue.md
构建完整的 UI 模式	references/recipes.md