Radix UI

Radix UI 包含低层级的 Radix Primitives 与提供默认视觉的 Radix Themes。Primitives 官方定位是用于构建高质量、可访问设计系统和 Web 应用的基础组件，重点在行为、WAI-ARIA 模式、组合和开发体验；它不会替团队决定品牌外观。

先选择 Primitives 还是 Themes

两者可以组合，但要明确样式所有权。

Primitive 解决浏览器缺失的行为

Dialog、Popover、Select、Dropdown Menu、Tabs 等控件需要键盘导航、焦点管理、ARIA 属性和关闭逻辑。Radix 提供这些底层行为，业务团队再决定 DOM 组合、视觉与内容。不要在封装时移除必要部件或用普通 div 替换触发器。

组合式 API 要保持结构关系

Root、Trigger、Content、Item 等部件可灵活排列，并通过 asChild 接入自定义元素。灵活不代表任意嵌套：触发器必须可聚焦，Label 与 Description 要正确关联，Portal 内容需考虑层级、容器和事件边界。

受控与非受控状态统一选择

• 简单局部交互可使用默认状态；
• 路由、表单或跨组件联动使用受控状态；
• 避免同一组件同时维护两份 open/selected；
• 异步关闭时保留 loading 与错误反馈；
• 服务端渲染检查初始值和 hydration。

样式依赖状态属性

Primitives 会暴露 data-state、data-disabled、data-side 等信息，团队可用 CSS、Tailwind 或其他方案设样式。设计系统应将这些状态集中映射为 token 和组件变体，不要让每个页面各写一套选择器；动画也应覆盖打开与关闭阶段。

Portal 与层叠上下文需要调试

Dialog、Popover 和 Tooltip 常通过 Portal 渲染，容易与固定导航、transform 容器和 z-index 体系冲突。建立统一 overlay 容器和层级表，检查滚动锁、点击外部、嵌套弹层与移动端软键盘，不能用不断加大 z-index 解决。

封装后才是团队组件

将选定 Primitive 包装成 Button、Dialog、Select 等内部组件，固定 token、尺寸、错误状态、埋点和测试。记录 Radix 版本与本地扩展，升级时回归键盘、焦点、屏幕阅读器和 Portal；底层可访问性是起点，业务组合仍需验收。