component-library

组件库 - shadcn/ui 架构

使用 shadcn/ui 模式生成可用于生产环境的 React 组件，每个项目可节省 8-10 小时。

快速开始

生成组件时：

1. 创建 /components/ui/ 目录结构
2. 首先生成带有 cn() 辅助函数的 lib/utils.ts
3. 创建所需组件，包含完整的 TypeScript、变体和无障碍支持
4. 为每个组件提供使用示例

核心配置文件

始终先生成这些文件：

lib/utils.ts - 必需的 cn() 辅助函数：

import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

components.json - 组件注册表：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

组件类别

表单组件

• Input - 带有多种变体（default、ghost、underline）的文本输入框
• Select - 支持搜索和多选选项的自定义下拉菜单
• Checkbox - 支持不确定状态
• Radio - 带自定义样式的单选按钮组
• Switch - 带标签的切换开关
• Textarea - 支持自动调整大小和字符计数的变体
• DatePicker - 集成日历，支持范围选择
• FileUpload - 支持拖放、预览和进度显示
• Slider - 带刻度和工具提示的范围输入框
• Form - 带验证的 React Hook Form 封装组件

展示组件

• Card - 带页眉/页脚插槽的容器
• Table - 支持排序、筛选和分页
• Badge - 带变体的状态指示器
• Avatar - 带后备显示的图片/首字母
• Progress - 线性和圆形变体
• Skeleton - 加载状态
• Separator - 视觉分隔线
• ScrollArea - 自定义滚动条

反馈组件

• Alert - 信息/警告/错误/成功状态
• Toast - 带操作项的通知
• Dialog/Modal - 无障碍覆盖层
• Tooltip - 悬停信息
• Popover - 定位内容
• AlertDialog - 确认对话框

导航组件

• Navigation - 带移动端菜单的响应式导航
• Tabs - 支持键盘导航的标签面板
• Breadcrumb - 路径导航
• Pagination - 页面控件
• CommandMenu - 命令面板（⌘K）
• ContextMenu - 右键菜单
• DropdownMenu - 操作菜单

布局组件

• Accordion - 可折叠分区
• Collapsible - 显示/隐藏内容
• ResizablePanels - 可拖动的分栏面板
• Sheet - 滑出式面板
• AspectRatio - 保持纵横比

组件实现模式

所有变体都使用 CVA：

import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

无障碍要求：

• 为所有交互元素添加 ARIA 标签和角色
• 支持键盘导航（Tab、方向键、Enter、Escape）
• 为模态框管理焦点并限制焦点范围
• 提供屏幕阅读器播报
• 使用语义化 HTML 元素

深色模式支持：

• 使用 Tailwind 的 dark: 修饰符
• 使用 CSS 变量定义主题颜色
• 支持模式间平滑过渡

响应式设计：

• 采用移动端优先的方法
• 在适当场景使用容器查询
• 使用便于触控的点击目标（最小 44x44px）
• 使用响应式排版比例

依赖项

在 package.json 中添加：

{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-progress": "^1.0.3",
    "@radix-ui/react-radio-group": "^1.1.3",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "cmdk": "^0.2.0",
    "date-fns": "^2.30.0",
    "lucide-react": "^0.263.1",
    "react-day-picker": "^8.8.0",
    "react-hook-form": "^7.45.4",
    "tailwind-merge": "^1.14.0",
    "tailwindcss-animate": "^1.0.7"
  }
}

实现工作流

1. 评估需求：确定所需组件
2. 生成基础文件：创建 utils.ts 和 components.json
3. 创建组件：生成所需组件及其全部功能
4. 提供示例：为每个组件提供使用示例
5. 记录 Props：添加带有 JSDoc 注释的 TypeScript 接口

高级模式

复杂需求请参阅：

• references/form-patterns.md - 高级表单处理
• references/data-tables.md - 复杂表格实现
• references/animation-patterns.md - Framer Motion 集成
• references/testing-setup.md - 组件测试模式

性能优化

• 对开销较大的组件使用 React.memo
• 为长列表实现虚拟滚动
• 延迟加载大型组件
• 通过 tree shaking 优化打包体积
• 使用 CSS containment 保持布局稳定

组件生成提示

生成组件时：

• 包含所有变体组合
• 添加适当的 TypeScript 类型
• 实现键盘快捷键
• 包含加载和错误状态
• 提供 Storybook 故事结构
• 添加全面的属性文档
• 包含无障碍属性
• 使用屏幕阅读器进行测试