Radix UI 设计系统技能：从无头组件构建可访问的 React 组件库

技能简介

Radix UI 设计系统技能（radix-ui-design-system）专为使用无头（headless）基础组件搭建组件库的前端团队而设计。Radix 提供了对话框、下拉菜单、标签页、选择器、提示气泡等组件的可访问性底座，但把它们组装成一套风格统一、主题可定制、无障碍达标的组件系统并不容易。本技能围绕 Radix 的架构、主题化与组件模式给出系统化指导，帮助团队在保留无障碍原语的前提下叠加自己的视觉体系，避免"为了好看而破坏可访问性"的常见问题。

核心能力

1. 可访问对话框与浮层：讲解如何基于 Radix 原语实现无障碍的对话框、下拉菜单、标签页、选择器、提示与手风琴组件。
2. 主题化策略：展示 CSS 变量、Tailwind 与 CVA 等手段，构建可切换主题的组件体系。
3. 组件模式：介绍复合组件、多态 asChild 用法与受控状态处理等高级模式。
4. 无障碍清单：提供焦点管理、ARIA 标签、键盘支持与对比度等检查项。
5. 疑难排查：覆盖传送门（Portal）、z-index 冲突、对话框行为异常与 TypeScript 报错等常见问题的排查思路。
6. 迁移与治理：指导如何从有主张的 UI 组件库平滑迁移到无头 Radix 原语，并保留设计令牌。

安装配置

1. 确认项目为 React 环境（Radix 依赖 React Hooks），并准备好 Node.js 工具链。
2. 安装命令：npx skillstore add sickn33/radix-ui-design-system。
3. 支持 Claude、Codex、Claude Code 等 AI 编程工具，安装后即可调用。
4. 采用 MIT 许可；技能中的安装命令均为供用户参考的示例，需由开发者自行执行。

使用步骤

1. 规划组件：列出需要构建的对话框、下拉菜单、标签页等组件及其交互要求。
2. 定义主题令牌：用 CSS 变量结合 Tailwind 规划颜色、间距、圆角、阴影与暗色模式。
3. 设计组件 API：确定复合组件的结构、asChild 用法、受控状态与变体命名。
4. 实现与自查：围绕 Radix 预期结构叠加样式，保留其无障碍原语，不随意覆盖键盘行为。
5. 测试无障碍：用真实辅助技术验证键盘导航、屏幕阅读器标签、焦点恢复与对比度。
6. 文档与迁移：补齐组件文档，并规划从旧组件库迁移的路径。

适用场景

• 创建组件库：为团队规划一套可复用、可主题化且满足无障碍要求的 Radix 组件。
• 改进无障碍模式：审查对话框、下拉菜单与表单的焦点处理、ARIA 覆盖与键盘支持。
• 迁移旧 UI 套件：用无头 Radix 原语替换有主张的组件，同时保留设计令牌与交互行为。
• 排查浮层问题：解决传送门、z-index、对话框行为与类型报错等疑难。

适用人群

使用 React 的前端工程师、组件库维护者、设计系统工程师，以及关注无障碍体验的产品团队。

工作原理

技能聚焦 Radix 在 React 中的使用方式，不会提供现成的完整视觉主题或品牌系统。它假定开发者保留 Radix 的无障碍原语（如对话框必须的标题与描述元素），在其预期结构之外叠加样式与主题令牌。技能给出的无障碍指导仍需结合真实辅助技术在具体项目中测试，安装命令仅作示例，不会由技能自动执行。其核心思路是"保留可访问性底座、在其上叠加一致的视觉层"，从而兼顾规范与效率。

官方链接

• 技能主页：https://skillstore.io/skills/sickn33-radix-ui-design-system
• 开源仓库：https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/radix-ui-design-system