Reka UI：给 Vue 用的无样式无障碍组件库，从安装到写一个 Popover

项目信息

• 仓库：https://github.com/unovue/reka-ui
• 官网：https://reka-ui.com
• 文档（Getting Started）：https://reka-ui.com/docs/overview/getting-started
• 示例：https://reka-ui.com/examples
• LLM 优化文档：https://reka-ui.com/llms.txt
• 许可：MIT
• Star：约 6785
• 当前版本：v2.10.4

Reka UI 是一个用 Vue.js 构建高质量、无障碍设计系统与 Web 应用的底层 UI 组件库。它想做的事是：把无障碍、可定制和开发体验这三件事做好，组件本身不提供任何视觉样式，你可以把它当成自己设计系统的地基，也可以渐进式地一个个接入现有项目。

从 Radix Vue 到 Reka UI

Reka UI 是 Radix Vue 在 v2 演进中的新身份。Reka 读作 /ree·kuh/，在马来语里意为“设计”，同时也让人联想到 “Eureka”。更名不改变它的定位：一个低层级组件库，只处理交互、状态与无障碍，把样式和业务语义留给你。

它受 Radix UI 的原则与目标启发。相关参考：Radix UI（https://radix-ui.com）、React Aria（https://react-spectrum.adobe.com/react-aria）、Floating UI（https://floating-ui.com）、VueUse（https://vueuse.org）、HeadlessUI（https://headlessui.com）、Ariakit（https://ariakit.org）。

设计原则

无障碍优先。 无障碍是 Reka UI 的核心。组件对齐 WAI-ARIA design patterns，aria 属性、键盘导航、焦点管理这些琐碎细节由库内部处理，开发者不必逐个组件重写一遍。

无样式、可定制。 组件不带样式，你可以用任何 CSS 方案来写：原生 CSS、预处理器或 CSS-in-JS。开放的组件结构允许你包装、扩展或改造每一个组件。

开放与模块化。 每个组件对内层元素的访问是细粒度的，加事件监听、传 props、挂 ref 都可以做到。

灵活的状态管理。 组件默认是非受控的（uncontrolled），需要时也可以完全受控。用多少状态管理由你决定。

面向开发者的体验。 API 保持一致且可预测，全量类型（fully-typed），asChild prop 让你完全掌控最终渲染出的元素。

性能与 Tree-shaking。 所有组件编译进单一包，安装简单；未使用的组件不会进入产物，由 tree-shaking 处理。

安装

pnpm add reka-ui
npm install reka-ui
yarn add reka-ui

上手：实现一个 Popover

1. 安装依赖

见上一节的安装命令。

2. 导入各个部件

import { PopoverArrow, PopoverClose, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'

More info

Some more info...

六个部件各司其职：PopoverRoot 承载状态，PopoverTrigger 是触发元素，PopoverPortal 决定内容挂载位置，PopoverContent 是浮层内容，PopoverClose 提供关闭入口，PopoverArrow 渲染指向箭头。

3. 加上自己的样式

More info

Some more info...

.PopoverTrigger { background-color: white; border-radius: 4px; }
.PopoverContent { border-radius: 4px; padding: 20px; width: 260px; background-color: white; }
.PopoverArrow { background-color: white; }

这些组件的层级足够低，怎么包装由你决定，你完全可以在此基础上封装一套适合自己团队和产品的高层 API。几步下来得到的是一个具备完整无障碍能力的 Popover：

• 遵循 WAI-ARIA design pattern
• 可受控，也可非受控
• 可自定义 side、alignment、offset 与碰撞处理
• 可选渲染指向箭头
• 焦点完全由库管理，且可定制
• 关闭行为与层级行为高度可定制

配合 LLM 使用

Reka UI 的文档针对大语言模型做了优化，提供了一种对 LLM 友好的格式：https://reka-ui.com/llms.txt 中包含所有组件的完整概览、API 文档、用法示例、无障碍指南与样式选项。要让模型帮你写 Reka UI 的代码，从这里取上下文比翻网页更直接。

什么时候用，什么时候不必用

适合用的情况：你正在自建设计系统，需要一套不预设视觉的底层原语——交互、焦点、键盘行为、ARIA 语义这些由库兜住，样式与业务语义由你自己定义；或者你已有成体系的样式规范，缺的只是可靠的浮层、菜单、对话框等交互组件，需要时可以逐个渐进接入，而不是一次性替换整个 UI 层。

不必用的情况：项目里已经有一套完整的 UI 库，组件风格、主题和交互都已满足需求，此时再引入一层无样式原语，只会多出一层需要自己维护的样式与封装工作，收益有限。