如何使用 Radix UI 构建无样式、高可访问性的组件库 #

解决 UI 开发中“样式与行为耦合”的痛点：通过使用 Radix UI 的 Headless 架构，在保留完整可访问性（Accessibility）和交互逻辑的同时，实现 100% 的视觉自定义控制。

为什么需要这个技能 #

在构建企业级设计系统时，开发者经常陷入两难：使用成熟的 UI 库（如 Ant Design, MUI）虽然快，但难以深度定制样式，且往往带有沉重的默认风格；而从零开始写 Modal、Dropdown 或 Tabs 等复杂组件，则需要处理繁琐的键盘导航、焦点管理和屏幕阅读器兼容性（WAI-ARIA 规范）。

Radix UI 采用了 Headless（无头）架构，它只提供组件的“行为”和“逻辑”，不提供任何“样式”。这意味着你可以直接使用它提供的可访问性保障，然后用 Tailwind CSS、CSS Variables 或 CSS-in-JS 随意定义外观，无需为了覆盖默认样式而写大量的 !important。

适用场景 #

• 从零开始创建公司内部的定制化设计系统。
• 构建需要通过 WCAG 2.1 AA/AAA 可访问性合规检查的政企项目。
• 现有的 UI 库样式过于臃肿，需要迁移到更轻量、可控的原语组件。
• 实现复杂的交互组件（如多级嵌套菜单、模态对话框、可组合的选项卡）。

核心工作流 #

1. 引入原语组件 #

根据需求安装特定的原语。例如安装对话框和下拉菜单：

npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

2. 组合组件结构 #

遵循 Root $\to$ Trigger $\to$ Portal $\to$ Content 的组合模式。

import * as Dialog from '@radix-ui/react-dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <button className="btn-primary">打开模态框</button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6">
          <Dialog.Title>确认操作</Dialog.Title>
          <Dialog.Description>此操作不可撤销。</Dialog.Description>
          <Dialog.Close asChild>
            <button>关闭</button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

3. 应用样式策略 #

• CSS 变量：定义全局主题色，在组件类名中引用。
• Tailwind + CVA：使用 class-variance-authority 管理组件的不同变体（如 Primary, Danger, Small, Large）。
• asChild 属性：这是 Radix 的核心，允许你将原语的行为传递给自定义的子元素，避免多余的 DOM 层级，确保语义化。

下载和安装 #

下载 radix-ui-design-system 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要 #

暂无推荐