使用 shadcn/ui 和 Radix Primitives 构建无障碍 UI 组件库 - CVA 变体与 OKLCH 主题指南

ui-components by yonatangross/orchestkit

236 周安装量

132 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/yonatangross/orchestkit --skill ui-components

UI组件库 CSS React

🇨🇳中文介绍

UI 组件

使用 shadcn/ui 和 Radix Primitives 构建无障碍 UI 组件库的综合模式。涵盖 CVA 变体、OKLCH 主题、cn() 工具函数、组件扩展、asChild 组合、对话框/菜单模式以及数据属性样式。每个类别在 rules/ 目录下都有独立的规则文件，按需加载。

快速参考

类别	规则数量	影响程度	使用场景
shadcn/ui	3	高	CVA 变体、组件定制、表单模式、数据表格
Radix Primitives	3	高	对话框、多态组合、数据属性样式
设计系统	5	高	W3C 令牌、OKLCH 主题、间距比例、排版、组件状态、动画
设计系统组件	1	高	原子设计、CVA 变体、无障碍性、Storybook
表单	2	高	React Hook Form v7、Zod 验证、服务器操作

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Tailwind CSS v4 + shadcn/ui 生产级技术栈配置指南与最佳实践

2,600 周安装

TanStack Query v5 完全指南：React 数据管理、乐观更新、离线支持

2,500 周安装

Vite Flare Starter：开箱即用的全栈Cloudflare应用模板，集成React 19、Hono、D1

437 周安装

React Native Testing Library (RNTL) 完整指南：v13/v14 版本差异、查询优先级与最佳实践

424 周安装

总计：7 个类别，共 21 条规则

// 使用 cn() 工具函数的 CVA 变体系统
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' },
  }
)



// 使用 asChild 组合的 Radix 对话框
import { Dialog } from 'radix-ui'

<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>打开</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="data-[state=open]:animate-in">
      <Dialog.Title>标题</Dialog.Title>
      <Dialog.Description>描述</Dialog.Description>
      <Dialog.Close>关闭</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

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

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

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

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

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

反模式（禁止）

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

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

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

规则	文件	关键模式
令牌架构	`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

结合 Zod 验证和 React 19 服务器操作的 React Hook Form v7。

规则	文件	关键模式
React Hook Form	`rules/forms-react-hook-form.md`	useForm、字段数组、Controller、向导、文件上传
Zod 与服务器操作	`rules/forms-validation-zod.md`	Zod 模式、服务器操作、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 视觉回归

基于认知科学的 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`	骨架屏优先、图标 + 标题 + 描述 + 行动号召、原因特定语气

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

🇺🇸English

UI Components

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.

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	5	HIGH	W3C tokens, OKLCH theming, spacing scales, typography, component states, animation
Design System Components	1	HIGH	Atomic design, CVA variants, accessibility, Storybook
Forms	2	HIGH	React Hook Form v7, Zod validation, Server Actions
Modern CSS & Tooling	3	HIGH	CSS cascade layers, Tailwind v4, Storybook CSF3
UX Foundations	4	HIGH	Visual hierarchy, typography thresholds, color system, empty states

Total: 21 rules across 7 categories

Quick Start

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

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

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

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

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

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

Design System

Design token architecture, spacing, typography, and interactive component states.

Rule	File	Key Pattern
Token Architecture	`rules/design-system-tokens.md`	W3C tokens, OKLCH colors, Tailwind @theme
Spacing Scale	`rules/design-system-spacing.md`	8px grid, Tailwind space-1 to space-12
Typography Scale	`rules/design-system-typography.md`	Font sizes, weights, line heights
Component States	`rules/design-system-states.md`	Hover, focus, active, disabled, loading, animation presets

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

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

Modern CSS & Tooling

Modern CSS patterns, Tailwind v4, and component documentation tooling for 2026.

Rule	File	Key Pattern
CSS Cascade Layers	`rules/css-cascade-layers.md`	@layer ordering, specificity-free overrides, third-party isolation
Tailwind v4	`rules/tailwind-v4-patterns.md`	CSS-first @theme, native container queries, @max-* variants
Storybook Docs	`rules/storybook-component-docs.md`	CSF3 stories, play() interaction tests, Chromatic visual regression

UX Foundations

Cognitive-science-grounded UI/UX principles with specific numeric thresholds for production-quality interfaces.

Rule	File	Key Pattern
Visual Hierarchy	`rules/visual-hierarchy.md`	Button tiers, de-emphasis, F/Z scan, Von Restorff, proximity, max-width
Typography Thresholds	`rules/typography-thresholds.md`	65ch line length, 1.4–1.6 line height, rem units, modular type scale
Color System	`rules/color-system.md`	OKLCH 9-shade scales, semantic categories, no true black, brand-tinted neutrals
Empty States	`rules/empty-states.md`	Skeleton-first, icon + headline + description + CTA, cause-specific tone

Related Skills

ork:accessibility - WCAG compliance and React Aria patterns
ork:testing-unit - Component testing patterns

Weekly Installs

236

Repository

yonatangross/orchestkit

GitHub Stars

132

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode222

codex211

gemini-cli207

cursor202

github-copilot195

claude-code194

使用 shadcn/ui 和 Radix Primitives 构建无障碍 UI 组件库 - CVA 变体与 OKLCH 主题指南

🇨🇳中文介绍

UI 组件

快速参考

相关 Skills

快速开始

shadcn/ui

Radix Primitives

关键决策

反模式（禁止）

详细文档

设计系统

设计系统组件

表单

现代 CSS 与工具

UX 基础

相关技能

🇺🇸English

UI Components

Quick Reference

Quick Start

shadcn/ui

Radix Primitives

Key Decisions

Anti-Patterns (FORBIDDEN)

Detailed Documentation

Design System

Design System Components

Forms

Modern CSS & Tooling

UX Foundations

Related Skills

最新 Skills