Radix UI 设计系统
使用 Radix UI 原语构建生产就绪、可访问的设计系统,拥有完全的定制控制权且无样式偏见。
概述
Radix UI 提供了无样式的、可访问的组件(原语),您可以对其进行定制以匹配任何设计系统。此技能指导您使用 Radix UI 构建可扩展的组件库,重点在于无障碍优先设计、主题架构和可组合模式。
主要优势:
- 无头设计:完全控制样式,无需对抗默认值
- 内建无障碍:符合 WAI-ARIA 规范,支持键盘导航和屏幕阅读器
- 可组合原语:通过简单的构建块构建复杂组件
- 框架无关:与 React 配合使用,但样式可随处应用
何时使用此技能
- 从头创建自定义设计系统
- 构建可访问的 UI 组件库
- 实现复杂的交互式组件(对话框、下拉菜单、选项卡等)
- 从样式化组件库迁移到无样式原语
- 使用 CSS 变量或 Tailwind 设置主题系统
- 需要完全控制组件行为和样式
- 构建需要符合 WCAG 2.1 AA/AAA 标准的应用程序
不使用此技能的情况
- 需要开箱即用的预样式组件(请使用 shadcn/ui、Mantine 等)
- 构建无需交互的简单静态页面
- 项目不使用 React 16.8+(Radix 需要 hooks)
- 需要用于非 React 框架的组件
核心原则
1. 无障碍优先
每个 Radix 原语都以无障碍为基石:
- 键盘导航:完整的键盘支持(Tab、方向键、回车、退出)
- 屏幕阅读器:正确的 ARIA 属性和动态区域
- 焦点管理:自动焦点捕获和恢复
- 禁用状态:正确处理 disabled 和 aria-disabled
规则:永远不要覆盖无障碍功能。增强,而非替代。
2. 无头架构
Radix 提供行为,您提供外观:
// ❌ 不要与预样式组件对抗
<Button className="override-everything" />
// ✅ Radix 给您行为,您添加样式
<Dialog.Root>
<Dialog.Trigger className="your-button-styles" />
<Dialog.Content className="your-modal-styles" />
</Dialog.Root>
3. 组合而非配置
从简单的原语构建复杂组件:
// 原语组件自然组合
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
<Tabs.Trigger value="tab2">标签 2</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">内容 1</Tabs.Content>
<Tabs.Content value="tab2">内容 2</Tabs.Content>
</Tabs.Root>
入门指南
安装
# 推荐:单独安装每个原语
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
# 或者一次安装多个
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
# 样式相关(可选但常见)
npm install clsx tailwind-merge class-variance-authority
基本组件模式
每个 Radix 组件遵循此模式:
import * as Dialog from '@radix-ui/react-dialog';
export function MyDialog() {
return (
<Dialog.Root>
{/* 触发对话框 */}
<Dialog.Trigger asChild>
<button className="trigger-styles">打开</button>
</Dialog.Trigger>
{/* Portal 在 DOM 层次结构外渲染 */}
<Dialog.Portal>
{/* 覆盖层(背景) */}
<Dialog.Overlay className="overlay-styles" />
{/* 内容(模态框) */}
<Dialog.Content className="content-styles">
<Dialog.Title>标题</Dialog.Title>
<Dialog.Description>描述</Dialog.Description>
{/* 您的内容放在这里 */}
<Dialog.Close asChild>
<button>关闭</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
主题策略
策略 1:CSS 变量(框架无关)
最佳适用:最大可移植性,SSR 友好
/* globals.css */
:root {
--color-primary: 220 90% 56%;
--color-surface: 0 0% 100%;
--radius-base: 0.5rem;
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
[data-theme="dark"] {
--color-primary: 220 90% 66%;
--color-surface: 222 47% 11%;
}
// Component.tsx
<Dialog.Content
className="
bg-[hsl(var(--color-surface))]
rounded-[var(--radius-base)]
shadow-[var(--shadow-lg)]
"
/>
策略 2:Tailwind + CVA (Class Variance Authority)
最佳适用:Tailwind 项目,变体丰富的组件
// button.tsx
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 focus-visible:outline-none 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",
ghost: "hover:bg-accent hover:text-accent-foreground",
},
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",
},
}
);
interface ButtonProps extends VariantProps<typeof buttonVariants> {
children: React.ReactNode;
}
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={cn(buttonVariants({ variant, size }))}>
{children}
</button>
);
}
策略 3:Stitches (CSS-in-JS)
最佳适用:运行时主题,作用域样式
import { styled } from '@stitches/react';
import * as Dialog from '@radix-ui/react-dialog';
const StyledContent = styled(Dialog.Content, {
backgroundColor: '$surface',
borderRadius: '$md',
padding: '$6',
variants: {
size: {
small: { width: '300px' },
medium: { width: '500px' },
large: { width: '700px' },
},
},
defaultVariants: {
size: 'medium',
},
});
组件模式
模式 1:带上下文的复合组件
使用场景:在原语部分之间共享状态
// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
export function CustomSelect({ items, placeholder, onValueChange }) {
return (
<Select.Root onValueChange={onValueChange}>
<Select.Trigger className="select-trigger">
<Select.Value placeholder={placeholder} />
<Select.Icon>
<ChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content className="select-content">
<Select.Viewport>
{items.map((item) => (
<Select.Item
key={item.value}
value={item.value}
className="select-item"
>
<Select.ItemText>{item.label}</Select.ItemText>
<Select.ItemIndicator>
<CheckIcon />
</Select.ItemIndicator>
</Select.Item>
))}
</Select.Viewport>
</Select.Content>
</Select.Portal>
</Select.Root>
);
}
模式 2:带 asChild 的多态组件
使用场景:渲染为不同元素而不丢失行为
// ✅ 渲染为 Next.js Link 但保留 Radix 行为
<Dialog.Trigger asChild>
<Link href="/settings">打开设置</Link>
</Dialog.Trigger>
// ✅ 渲染为自定义组件
<DropdownMenu.Item asChild>
<YourCustomButton icon={<Icon />}>操作</YourCustomButton>
</DropdownMenu.Item>
为什么 asChild 很重要:防止在无障碍树中出现嵌套按钮/链接问题。
模式 3:受控 vs 非受控
// 非受控(Radix 管理状态)
<Tabs.Root defaultValue="tab1">
<Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
</Tabs.Root>
// 受控(您管理状态)
const [activeTab, setActiveTab] = useState('tab1');
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
</Tabs.Root>
规则:当需要与外部状态(URL、Redux 等)同步时,使用受控模式。
模式 4:使用 Framer Motion 制作动画
import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';
export function AnimatedDialog({ open, onOpenChange }) {
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal forceMount>
<AnimatePresence>
{open && (
<>
<Dialog.Overlay asChild>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="dialog-overlay"
/>
</Dialog.Overlay>
<Dialog.Content asChild>
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
className="dialog-content"
>
{/* 内容 */}
</motion.div>
</Dialog.Content>
</>
)}
</AnimatePresence>
</Dialog.Portal>
</Dialog.Root>
);
}
常见原语参考
对话框(模态框)
<Dialog.Root> {/* 状态容器 */}
<Dialog.Trigger /> {/* 打开对话框 */}
<Dialog.Portal> {/* 在 portal 中渲染 */}
<Dialog.Overlay /> {/* 背景 */}
<Dialog.Content> {/* 模态框内容 */}
<Dialog.Title /> {/* 无障碍必需 */}
<Dialog.Description /> {/* 无障碍必需 */}
<Dialog.Close /> {/* 关闭对话框 */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
下拉菜单
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item />
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub> {/* 嵌套菜单 */}
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
选项卡
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1" />
<Tabs.Trigger value="tab2" />
</Tabs.List>
<Tabs.Content value="tab1" />
<Tabs.Content value="tab2" />
</Tabs.Root>
工具提示
<Tooltip.Provider delayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Content side="top" align="center">
工具提示文本
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
弹出框
<Popover.Root>
<Popover.Trigger />
<Popover.Portal>
<Popover.Content side="bottom" align="start">
内容
<Popover.Arrow />
<Popover.Close />
</Popover.Content>
</Popover.Portal>
</Popover.Root>
无障碍检查清单
每个组件必须包含:
- 焦点管理:所有交互元素上的可见焦点指示器
- 键盘导航:完整的键盘支持(Tab、方向键、回车、Esc)
- ARIA 标签:为屏幕阅读器提供有意义的标签
- 颜色对比度:符合 WCAG AA 最低要求(文本 4.5:1,UI 元素 3:1)
- 错误状态:使用
aria-invalid和aria-describedby提供清晰的错误消息 - 加载状态:异步操作期间使用适当的
aria-busy
对话框特定:
-
Dialog.Title已存在(屏幕阅读器必需) -
Dialog.Description提供上下文 - 模态框打开时焦点被捕获在内部
- 按 Escape 键关闭对话框
- 关闭后焦点返回到触发器
下拉菜单特定:
- 方向键导航项目
- 输入搜索功能正常
- 首/尾项目包裹行为
- 选中状态通过视觉和 ARIA 指示
最佳实践
✅ 应做事项
-
始终使用
asChild避免包装 div<Dialog.Trigger asChild> <button>打开</button> </Dialog.Trigger> -
提供语义化 HTML
<Dialog.Content asChild> <article role="dialog" aria-labelledby="title"> {/* 内容 */} </article> </Dialog.Content> -
使用 CSS 变量进行主题设置
.dialog-content { background: hsl(var(--surface)); color: hsl(var(--on-surface)); } -
组合原语构建复杂组件
function CommandPalette() { return ( <Dialog.Root> <Dialog.Content> <Combobox /> {/* 对话框内的 Radix Combobox */} </Dialog.Content> </Dialog.Root> ); }
❌ 不应做事项
-
不要跳过无障碍部分
// ❌ 缺少 Title 和 Description <Dialog.Content> <div>内容</div> </Dialog.Content> -
不要与原语对抗
// ❌ 覆盖内部行为 <Dialog.Content onClick={(e) => e.stopPropagation()}> -
不要混合受控和非受控
// ❌ 状态管理不一致 <Tabs.Root defaultValue="tab1" value={activeTab}> -
不要忽略键盘导航
// ❌ 禁用键盘行为 <DropdownMenu.I
}```