# 用户界面组件使用 shadcn/ui 和 Radix Primitives 构建可访问的 UI 组件库的综合模式。涵盖 CVA 变体、OKLCH 主题、cn() 实用程序、组件扩展、asChild 组合、对话框/菜单模式和数据属性样式。每个类别在“rules/”中都有按需加载的单独规则文件。 ## 快速参考类别 |规则|影响 |何时使用 ---|---|---|--- shadcn/ui | 3 |高| CVA 变体、组件定制、表单模式、数据表基数基元 | 3 |高|对话框、多态组合、数据属性样式设计系统| 5 |高| W3C 令牌、OKLCH 主题、间距比例、版式、组件状态、动画设计系统组件| 1 |高|原子设计、CVA 变体、可访问性、故事书表格 | 2 |高| React Hook Form v7、Zod 验证、服务器操作现代 CSS 和工具 | 3 |高| CSS 级联层、Tailwind v4、Storybook CSF3 用户体验基础 | 4 |高|视觉层次、排版阈值、颜色系统、空状态 **总计：7 个类别 21 条规则** ## 快速入门 // 具有 cn() 实用程序的 CVA 变体系统从 'class-variance-authority' 导入 { cva, type VariantProps } 从 '@/lib/utils' 导入 { cn } const 按钮变体 = cva( 'inline-flex items-center justify-center rounded-md font-mediumtransition-colors', { 变体：{ 变体：{ 默认值：'bg-primary text-primary-foreground悬停：bg-primary/90'，破坏性的：'bg-破坏性文本-破坏性-前景'，大纲：'边框边框-输入bg-背景悬停：bg-accent'， Ghost: '悬停:bg-accent 悬停:text-accent-foreground', }, 尺寸：{ 默认值：'h-10 px-4 py-2'， sm: 'h-9 px-3', lg: 'h-11 px-8', }, }, defaultVariants: { 变体: '默认', 大小: '默认' }, } ） // 带有 asChild 组合的 Radix Dialog 从 'radix-ui' 导入 { Dialog } <对话框.根> <按钮>打开 <对话.传送门> 标题描述关闭 ## shadcn/ui 设计精美、易于访问的组件基于 CVA 变体、cn() 实用程序和 OKLCH 主题构建。规则|文件|按键模式 ---|---|--- 定制| `rules/shadcn-customization.md` | CVA 变体、cn() 实用程序、OKLCH 主题、组件扩展表格 | `规则/shadcn-forms.md` |表单字段包装、react-hook-form 集成、验证数据表| `rules/shadcn-data-table.md` | TanStack 表集成、列定义、排序/过滤 ## 基数原语无样式、可访问的 React 原语，用于构建高质量的设计系统。规则|文件|按键模式 ---|---|--- 对话| `rules/radix-dialog.md` |对话框、AlertDialog、受控状态、动画成分| `rules/radix-composition.md` | asChild、Slot、嵌套触发器、多态渲染造型 | `rules/radix-styling.md` |数据属性、Tailwind 任意变体、焦点管理 ## 关键决策决定|推荐 ---|--- 颜色格式| OKLCH 用于感知统一的主题类合并|始终使用 cn() 解决 Tailwind 冲突扩展组件|换行，不要修改源文件变体 |使用 CVA 实现类型安全的多轴变体造型方法|数据属性+Tailwind任意变体成分|使用 `asChild` 来避免包装 div 动画|仅 CSS 且具有数据状态选择器表单组件 |与react-hook-form结合 ## 反模式（禁止） * **修改 shadcn 源** ：换行并扩展而不是编辑生成的文件 * **跳过 cn()** ：直接字符串连接会导致 Tailwind 类冲突 * **CVA 上的内联样式**：使用 CVA 实现类型安全、可重用的变体 * **包装 div** ：使用 `asChild` 来避免额外的 DOM 元素 * **Missing Dialog.Title** ：每个对话框都必须有一个可访问的标题 * **正 tabindex** ：使用 `tabindex > 0` 会破坏自然的 Tab 顺序 * **仅颜色状态** ：使用数据属性+多个指标 * **手动对焦管理** ：使用 Radix 内置焦点陷印 ## 详细文档资源 |描述 ---|--- [脚本/]() |模板：CVA 组件、扩展按钮、对话框、下拉菜单 [checklists/]() | shadcn 设置、可访问性审核清单 [参考文献/]() | CVA 系统、OKLCH 主题、cn() 实用程序、焦点管理 ## 设计系统设计令牌架构、间距、排版和交互组件状态。规则|文件|按键模式 ---|---|--- 代币架构| `rules/design-system-tokens.md` | W3C 令牌、OKLCH 颜色、Tailwind @主题间距比例| `规则/设计系统间距.md` | 8px 网格，Tailwind space-1 到 space-12 版式比例| `rules/design-system-typography.md` |字体大小、粗细、行高组件状态 | `规则/设计系统状态.md` |悬停、焦点、活动、禁用、加载、动画预设 ## 设计系统组件具有原子设计和可访问性的组件架构模式。规则|文件|按键模式 ---|---|--- 组件架构| `规则/设计系统组件.md` |原子设计、CVA 变体、WCAG 2.1 AA、故事书 ## 表格 React Hook Form v7 与 Zod 验证和 React 19 服务器操作。规则|文件|按键模式 ---|---|--- 反应钩子形式| `规则/forms-react-hook-form.md` | useForm、字段数组、控制器、向导、文件上传 Zod 和服务器操作 | `规则/表单验证-zod.md` | Zod 架构、服务器操作、useActionState、异步验证 ## 现代 CSS 和工具 2026 年的现代 CSS 模式、Tailwind v4 和组件文档工具。规则|文件|按键模式 ---|---|--- CSS 级联层 | `rules/css-cascade-layers.md` | @层排序、无特殊性覆盖、第三方隔离顺风 v4 | `规则/tailwind-v4-patterns.md` | CSS-first @theme、本机容器查询、@max-* 变体故事书文档 | `rules/storybook-component-docs.md` | CSF3 故事、play() 交互测试、色彩视觉回归 ## 用户体验基础基于认知科学的 UI/UX 原则，具有生产质量界面的特定数字阈值。规则|文件|按键模式 ---|---|--- 视觉层次| `规则/视觉层次结构.md` |按钮层、去加重、F/Z 扫描、Von Restorff、接近度、最大宽度版式阈值| `rules/typography-thresholds.md` | 65ch 行长、1.4–1.6 行高、rem 单位、模块化类型刻度色彩系统| `规则/颜色系统.md` | OKLCH 9 色度、语义类别、非纯黑色、品牌色调中性色空状态| `规则/空状态.md` |骨架优先，图标+标题+描述+CTA，针对具体原因的语气 ## 相关技能 * `ork:accessibility` \- WCAG 合规性和 React Aria 模式 * `ork:testing-unit` \- 组件测试模式

用户界面组件

包含技能