radix-ui-design-system

Radix UI 设计系统构建技能

技能概述

Radix UI Design System 是一个帮助开发者使用 Radix UI Primitives 构建生产级、可访问设计系统的技能指南，提供完整的组件定制、主题策略和无障碍实现方案。

适用场景

1. 构建自定义设计系统

当你需要从零开始创建一套符合品牌规范的设计系统时，Radix UI 提供了无样式的组件原语，让你完全掌控每个组件的视觉表现，同时内置的键盘导航、ARIA 属性和焦点管理确保了无障碍合规性，无需重复造轮子。

2. 实现复杂交互组件

对于 Dialog（对话框）、Dropdown Menu（下拉菜单）、Tabs（标签页）、Tooltip（提示框）等需要复杂状态管理和无障碍支持的交互组件，Radix UI 已经处理好了 Portal 渲染、焦点陷阱、键盘导航等底层逻辑，你只需要关注样式定制。

3. 需要完全控制样式的项目

如果你使用 Tailwind CSS、CSS Modules 或 styled-components 等样式方案，并且希望组件库能够无缝集成，Radix UI 的无样式架构让你能够完全自定义组件外观，不会像使用预样式组件库那样需要大量覆盖默认样式。

核心功能

1. 无障碍优先的组件原语

Radix UI 的每个组件都内置了 WAI-ARIA 规范支持，包括完整的键盘导航（Tab、箭头键、Enter、Escape）、屏幕阅读器兼容、自动焦点管理和禁用状态处理。例如，Dialog 组件会自动处理焦点陷阱、Escape 关闭和焦点返回到触发器，这些都是符合 WCAG 2.1 AA/AAA 标准的最佳实践。

2. 灵活的主题定制策略

支持三种主流主题方案：CSS Variables（适合跨框架使用）、Tailwind + CVA（适合 Tailwind 项目）、Stitches（适合运行时主题）。通过 asChild 属性可以实现多态组件，让 Radix UI 的行为层与你现有的样式层完美结合，无需打破现有的组件架构。

3. 复合组件模式

Radix UI 采用复合组件架构，通过 Context 共享状态，让复杂组件的组合变得直观自然。例如 Tabs 组件由 Tabs.Root、Tabs.List、Tabs.Trigger 和 Tabs.Content 组成，每个部分都可以独立使用或组合使用。配合 Controlled/Uncontrolled 两种状态管理模式，可以灵活适配各种应用架构（Redux、URL 状态、表单状态等）。

常见问题

Radix UI 和 shadcn/ui 有什么区别？

Radix UI 是底层的无样式组件原语库，提供行为和交互逻辑但不包含样式；shadcn/ui 是基于 Radix UI + Tailwind 构建的预样式组件集合。如果你需要快速搭建原型且接受标准设计，用 shadcn/ui；如果你需要完全定制且符合品牌规范，直接用 Radix UI。两者可以共存，shadcn/ui 本质上就是复制粘贴 Radix UI 的封装代码。

Radix UI 组件支持哪些框架？

Radix UI 当前只有 React 版本（需要 React 16.8+），但其样式方案是框架无关的——你可以使用 CSS Variables 或 Tailwind 在任何框架中复用相同的样式代码。对于 Vue、Svelte 等框架，可以选择 Headless UI、Ark UI 等类似理念的替代方案。

如何解决 Radix UI 组件的动画问题？

Radix UI 的 Portal 组件默认会在内容隐藏时立即卸载，导致动画无法播放。解决方案是使用 forceMount 属性强制挂载内容，结合 Framer Motion 的 AnimatePresence 组件来控制动画时机。具体做法是在 Dialog.Portal 上添加 forceMount，然后用 AnimatePresence 包裹带动画的 Dialog.Content，通过 open 状态控制进出场动画。