ui-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI Components

UI组件

Comprehensive patterns for building accessible UI component libraries with shadcn/ui and Radix Primitives. Covers CVA variants, OKLCH theming, cn() utility, component extension, asChild composition, dialog/menu patterns, and data-attribute styling. Each category has individual rule files in

rules/

loaded on-demand.

使用shadcn/ui和Radix Primitives构建无障碍UI组件库的综合模式。涵盖CVA变体、OKLCH主题、cn()工具函数、组件扩展、asChild组合、对话框/菜单模式以及数据属性样式。每个分类在

rules/

目录下都有按需加载的独立规则文件。

Quick Reference

快速参考

Category	Rules	Impact	When to Use
shadcn/ui	3	HIGH	CVA variants, component customization, form patterns, data tables
Radix Primitives	3	HIGH	Dialogs, polymorphic composition, data-attribute styling
Design System Tokens	1	HIGH	W3C tokens, OKLCH theming, Tailwind @theme, spacing scales
Design System Components	1	HIGH	Atomic design, CVA variants, accessibility, Storybook
Forms	2	HIGH	React Hook Form v7, Zod validation, Server Actions

Total: 10 rules across 4 categories

分类	规则数量	影响程度	使用场景
shadcn/ui	3	高	CVA变体、组件自定义、表单模式、数据表格
Radix Primitives	3	高	对话框、多态组合、数据属性样式
设计系统令牌	1	高	W3C令牌、OKLCH主题、Tailwind @theme、间距尺度
设计系统组件	1	高	原子设计、CVA变体、无障碍、Storybook
表单	2	高	React Hook Form v7、Zod验证、Server Actions

总计：4个分类下的10条规则

Quick Start

快速开始

tsx

// 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' },
  }
)

tsx

// 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>

tsx

// 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' },
  }
)

tsx

// 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

Beautifully designed, accessible components built on CVA variants, cn() utility, and OKLCH theming.

Rule	File	Key Pattern
Customization	`rules/shadcn-customization.md`	CVA variants, cn() utility, OKLCH theming, component extension
Forms	`rules/shadcn-forms.md`	Form field wrappers, react-hook-form integration, validation
Data Table	`rules/shadcn-data-table.md`	TanStack Table integration, column definitions, sorting/filtering

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

规则	文件	核心模式
自定义	`rules/shadcn-customization.md`	CVA变体、cn()工具函数、OKLCH主题、组件扩展
表单	`rules/shadcn-forms.md`	表单字段包装器、react-hook-form集成、验证
数据表格	`rules/shadcn-data-table.md`	TanStack Table集成、列定义、排序/筛选

Radix Primitives

Unstyled, accessible React primitives for building high-quality design systems.

Rule	File	Key Pattern
Dialog	`rules/radix-dialog.md`	Dialog, AlertDialog, controlled state, animations
Composition	`rules/radix-composition.md`	asChild, Slot, nested triggers, polymorphic rendering
Styling	`rules/radix-styling.md`	Data attributes, Tailwind arbitrary variants, focus management

用于构建高质量设计系统的无样式、无障碍React基础组件。

规则	文件	核心模式
对话框	`rules/radix-dialog.md`	Dialog、AlertDialog、受控状态、动画
组合	`rules/radix-composition.md`	asChild、Slot、嵌套触发器、多态渲染
样式	`rules/radix-styling.md`	数据属性、Tailwind任意变体、焦点管理

Key Decisions

核心决策

Decision	Recommendation
Color format	OKLCH for perceptually uniform theming
Class merging	Always use cn() for Tailwind conflicts
Extending components	Wrap, don't modify source files
Variants	Use CVA for type-safe multi-axis variants
Styling approach	Data attributes + Tailwind arbitrary variants
Composition	Use `asChild` to avoid wrapper divs
Animation	CSS-only with data-state selectors
Form components	Combine with react-hook-form

决策	推荐方案
颜色格式	使用OKLCH实现感知均匀的主题
类名合并	始终使用cn()解决Tailwind类名冲突
扩展组件	包装组件而非修改源文件
变体	使用CVA实现类型安全的多轴变体
样式方法	数据属性 + Tailwind任意变体
组合方式	使用 `asChild` 避免额外的包装div
动画	结合data-state选择器的纯CSS动画
表单组件	与react-hook-form结合使用

Anti-Patterns (FORBIDDEN)

反模式（禁止）

Modifying shadcn source: Wrap and extend instead of editing generated files
Skipping cn(): Direct string concatenation causes Tailwind class conflicts
Inline styles over CVA: Use CVA for type-safe, reusable variants
Wrapper divs: Use
```
asChild
```
to avoid extra DOM elements
Missing Dialog.Title: Every dialog must have an accessible title
Positive tabindex: Using
```
tabindex > 0
```
disrupts natural tab order
Color-only states: Use data attributes + multiple indicators
Manual focus management: Use Radix built-in focus trapping

修改shadcn源文件：应通过包装和扩展来实现，而非编辑生成的文件
跳过cn()：直接字符串拼接会导致Tailwind类名冲突
内联样式替代CVA：使用CVA实现类型安全、可复用的变体
多余包装div：使用
```
asChild
```
避免额外的DOM元素
缺失Dialog.Title：每个对话框必须包含无障碍标题
正tabindex值：使用
```
tabindex > 0
```
会破坏自然的制表符顺序
仅依赖颜色区分状态：使用数据属性 + 多种指示器
手动管理焦点：使用Radix内置的焦点捕获功能

Detailed Documentation

详细文档

Resource	Description
scripts/	Templates: CVA component, extended button, dialog, dropdown
checklists/	shadcn setup, accessibility audit checklists
references/	CVA system, OKLCH theming, cn() utility, focus management

资源	描述
scripts/	模板：CVA组件、扩展按钮、对话框、下拉菜单
checklists/	shadcn设置、无障碍审计检查清单
references/	CVA系统、OKLCH主题、cn()工具函数、焦点管理

Design System Tokens

设计系统令牌

Design token architecture for consistent theming and visual identity.

Rule	File	Key Pattern
Token Architecture	`rules/design-system-tokens.md`	W3C tokens, OKLCH colors, Tailwind @theme, spacing scales

用于实现一致主题和视觉标识的设计令牌架构。

规则	文件	核心模式
令牌架构	`rules/design-system-tokens.md`	W3C令牌、OKLCH颜色、Tailwind @theme、间距尺度

Design System Components

设计系统组件

Component architecture patterns with atomic design and accessibility.

Rule	File	Key Pattern
Component Architecture	`rules/design-system-components.md`	Atomic design, CVA variants, WCAG 2.1 AA, Storybook

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

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

Forms

表单

React Hook Form v7 with Zod validation and React 19 Server Actions.

Rule	File	Key Pattern
React Hook Form	`rules/forms-react-hook-form.md`	useForm, field arrays, Controller, wizards, file uploads
Zod & Server Actions	`rules/forms-validation-zod.md`	Zod schemas, Server Actions, useActionState, async validation

结合Zod验证和React 19 Server Actions的React Hook Form v7。

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

ui-components

Original

Translation

UI Components

UI组件

Quick Reference

快速参考

Quick Start

快速开始

shadcn/ui

shadcn/ui

Radix Primitives

Radix Primitives

Key Decisions

核心决策

Anti-Patterns (FORBIDDEN)

反模式（禁止）

Detailed Documentation

详细文档

Design System Tokens

设计系统令牌

Design System Components

设计系统组件

Forms

表单

Related Skills

相关技能