ui-components

UI 组件

使用 shadcn/ui 和 Radix Primitives 构建无障碍 UI 组件库的模式，作为一层薄封装，补充一手文档：快速入门配方、关键决策、反模式和本项目的增补内容。供应商机制（CVA 变体、cn() 工具、组件扩展、asChild 组合、对话框/菜单模式、数据属性样式）由上游负责；请参阅上游覆盖内容（勿重复说明）。其余各类别均在 rules/ 中提供单独的规则文件，按需加载。

快速参考

类别	规则	影响	使用时机
shadcn/ui	1	高	v4 样式、预设代码、样式检测
设计系统	4	高	W3C 令牌、OKLCH 主题、间距比例、排版、组件状态、动画
设计系统组件	1	高	原子设计、CVA 变体、无障碍、Storybook
表单	2	高	React Hook Form v7、Zod 验证、Server Actions
现代 CSS 与工具	3	高	CSS 级联层、Tailwind v4、Storybook CSF3
UX 基础	4	高	视觉层次、排版阈值、色彩系统、空状态

共计：6 个类别下的 15 条规则。 Radix 原语机制和 shadcn 定制教程已由一手文档说明；请参阅 上游覆盖内容（勿重复说明）以及 references/ork-delta.md，了解哪些内容由我们负责。

快速入门

// CVA variant system with cn() utility
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
      },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  }
)

// Radix Dialog with asChild composition
import { Dialog } from 'radix-ui'

<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>Open</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="data-[state=open]:animate-in">
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

shadcn/ui

基于 CVA 变体、cn() 工具和 OKLCH 主题构建的精美无障碍组件。

规则	文件	核心模式
v4 样式	rules/shadcn-v4-styles.md	6 种样式（Vega→Luma）、预设代码、样式检测、类映射

定制、表单和数据表教程现在由上游负责；请参阅 上游覆盖内容（勿重复说明）。在此基础上的本项目约定见 references/ork-delta.md。

v4 样式系统

shadcn CLI v4 提供 6 种视觉样式。每种样式都会重写组件类名，而不只是 CSS 变量。

样式	特征	适用场景
Vega	均衡的圆角、简洁的线条	通用场景（New York 的继任者）
Nova	紧凑的内边距、较小的边距	高密度仪表板、管理面板
Maia	柔和圆润、宽裕的间距	面向消费者的友好型应用
Lyra	锐利、零圆角、等宽字体组合	编辑类产品、开发者工具
Mira	超紧凑、极简的界面装饰	电子表格、数据密集型界面
Luma	极度圆润（rounded-4xl）、柔和的立体感（shadow-md + ring）、宽松的布局	精致的原生应用体验，灵感来自 macOS Tahoe

在 ui.shadcn.com/create 上通过可视化方式配置 → 选择样式、主题、字体和图标，然后复制生成的命令。不要在文档中硬编码预设代码——它们绑定于特定的样式快照，可能会发生变化。

shadcn CLI v4（2026 年 4 月）——新命令

命令	用途
npx shadcn@latest apply <style>	将已发布的样式（例如 luma、nova、lyra）应用到当前项目——为现有组件换肤，无需重新添加组件
npx shadcn@latest info	显示解析后的配置：注册表、样式、令牌、现有组件、Tailwind 版本
npx shadcn@latest skills	列出 shadcn/skills 注册表——适用于 Claude Code 和 Cursor 的技能包，集成 CLI 命令与 Agent 指引
npx shadcn@latest build	构建自定义注册表（已有文档说明）——配合 apply 发布私有样式

**检测：**读取 components.json → "style" 字段（例如 "radix-luma"、"base-nova"）。旧版 "new-york" 和 "default" 样式已由 Vega 取代。

关键决策

决策	建议
颜色格式	使用 OKLCH，实现视觉均匀的主题配色
类名合并	始终使用 cn() 解决 Tailwind 冲突
扩展组件	使用包装器，不要修改源文件
变体	使用 CVA 实现类型安全的多轴变体
样式方案	使用数据属性 + Tailwind 任意变体
组合	使用 asChild 避免包装器 div
动画	仅使用 CSS，并通过 data-state 选择器控制
表单组件	与 react-hook-form 结合使用
破坏性操作确认	使用 AlertDialog，绝不要使用普通 Dialog（参见 references/ork-delta.md）

反模式（禁止）

• 修改 shadcn 源码：使用包装器进行扩展，不要编辑生成的文件
• 跳过 cn()：直接拼接字符串会导致 Tailwind 类冲突
• 用内联样式替代 CVA：使用 CVA 实现类型安全且可复用的变体
• 使用包装器 div：使用 asChild 避免额外的 DOM 元素
• 缺少 Dialog.Title：每个对话框都必须有可访问的标题
• 使用正值 tabindex：使用 tabindex > 0 会打乱自然的 Tab 顺序
• 仅通过颜色表示状态：使用数据属性 + 多种指示方式
• 手动管理焦点：使用 Radix 内置的焦点陷阱

上游覆盖内容（不要重复说明）

这些主题于 2026-07-31 从此技能中移除，因为它们已有第一方来源负责。将会话引导至该来源；这里只保留底线、教训和团队决策（详见 references/ork-delta.md）。

主题	第一方来源
shadcn 设置、初始化清单、添加组件	vercel:shadcn（市场技能），https://ui.shadcn.com/docs/installation
shadcn 自定义、CVA 变体、cn() 工具函数、组件扩展	vercel:shadcn（市场技能），https://ui.shadcn.com/docs 和 https://cva.style/docs
OKLCH 主题变量、浅色/深色 CSS 变量集	https://ui.shadcn.com/docs/theming
使用 next-themes 切换深色模式	https://ui.shadcn.com/docs/dark-mode 和 https://github.com/pacocoursey/next-themes
使用 TanStack Table 创建数据表	https://ui.shadcn.com/docs/components/data-table 和 https://tanstack.com/table
表单字段包装器和校验状态	https://ui.shadcn.com/docs/components/form
Radix Dialog 和 AlertDialog 模式	https://www.radix-ui.com/primitives/docs/components/dialog 和 .../components/alert-dialog
Radix asChild / Slot 组合	https://www.radix-ui.com/primitives/docs/guides/composition
Radix 数据属性样式和焦点管理	https://www.radix-ui.com/primitives/docs/guides/styling
下拉菜单、弹出框、工具提示、悬停卡片	https://www.radix-ui.com/primitives/docs/components/dropdown-menu（以及同系列组件页面）
Radix 无障碍审查清单	https://www.radix-ui.com/primitives/docs/overview/accessibility 加上 ork:accessibility

详细文档

资源	说明
scripts/	模板：CVA 组件、扩展按钮、对话框、下拉菜单、主题 CSS
references/ork-delta.md	未纳入上游文档的 Ork 底线、教训和团队决策

设计系统

设计令牌架构、间距、排版和交互组件状态。

规则	文件	关键模式
令牌架构	rules/design-system-tokens.md	W3C 令牌、OKLCH 颜色、Tailwind @theme
间距比例	rules/design-system-spacing.md	8px 网格、Tailwind space-1 至 space-12
排版比例	rules/design-system-typography.md	字体大小、字重、行高
组件状态	rules/design-system-states.md	悬停、焦点、激活、禁用、加载、动画预设

设计系统组件

采用原子设计和无障碍模式的组件架构。

规则	文件	核心模式
组件架构	rules/design-system-components.md	原子设计、CVA 变体、WCAG 2.1 AA、Storybook

表单

使用 React Hook Form v7、Zod 验证和 React 19 Server Actions。

规则	文件	核心模式
React Hook Form	rules/forms-react-hook-form.md	useForm、字段数组、Controller、向导、文件上传
Zod 和 Server Actions	rules/forms-validation-zod.md	Zod 模式、Server Actions、useActionState、异步验证

现代 CSS 和工具

面向 2026 年的现代 CSS 模式、Tailwind v4 和组件文档工具。

规则	文件	核心模式
CSS 层叠层	rules/css-cascade-layers.md	@layer 排序、不受特异性影响的覆盖、第三方隔离
Tailwind v4	rules/tailwind-v4-patterns.md	CSS 优先的 @theme、原生容器查询、@max-* 变体
Storybook 文档	rules/storybook-component-docs.md	CSF3 故事、play() 交互测试、Chromatic 视觉回归

UX 基础

以认知科学为依据的 UI/UX 原则，提供适用于生产级界面的具体数值阈值。

规则	文件	核心模式
视觉层级	rules/visual-hierarchy.md	按钮层级、弱化强调、F/Z 扫视、冯·雷斯托夫效应、邻近性、最大宽度
排版阈值	rules/typography-thresholds.md	65ch 行长、1.4–1.6 行高、rem 单位、模块化字号比例
色彩系统	rules/color-system.md	OKLCH 9 级色阶、语义分类、避免纯黑、品牌色调中性色
空状态	rules/empty-states.md	优先使用骨架屏、图标 + 标题 + 描述 + CTA、根据原因调整语气

相关技能

• ork:accessibility - WCAG 合规性和 React Aria 模式
• ork:testing-unit - 组件测试模式