用 Reka UI 构建无样式可访问 Vue 3…

在 Vue 3 项目中用 Reka UI（原 Radix Vue）实现 WAI-ARIA 合规的无样式组件时，按需加载组件文档并应用安装、受控/非受控、asChild、虚拟化等做法。

适用场景

解决思路

1. 以 Reka UI v2.8.0（2026年1月）为当前版本，按该版本 API 和变更使用；它提供无样式、可访问、遵循 WAI-ARIA 的 Vue 3 组件原语，原名为 Radix Vue。
2. 按分类浏览组件索引用 `references/components.md`；查单个组件细节用 `components/*.md`（如 `dialog.md`、`select.md`）。
3. 根据当前任务只加载相关参考文件；只有在浏览组件分类索引或搜索特定组件时才加载 `references/components.md`，不要一次性加载全部文件。
4. 需要 Styling、Animation、Composition、SSR、Namespaced、Dates、i18n、Controlled State、Inject Context、Virtualization、Migration 等指南时，查阅 reka-ui.com 对应指南。
5. 在 `nuxt.config.ts` 中用 `modules: ['reka-ui/nuxt']` 安装并自动导入所有组件。
6. 在 `vite.config.ts` 中从 `reka-ui/resolver` 导入 `RekaResolver`，使用 `unplugin-vue-components/vite` 的 `Components` 插件并传入 `resolvers: [RekaResolver()]`。
7. 构建 Dialog 受控状态：使用 `DialogRoot`、`DialogTrigger`、`DialogPortal`、`DialogOverlay`、`DialogContent`、`DialogTitle`、`DialogDescription`、`DialogClose`，用 `v-model:open` 控制打开状态。
8. 构建 Select 非受控默认值：使用 `SelectRoot`、`SelectTrigger`、`SelectValue`、`SelectPortal`、`SelectContent`、`SelectViewport`、`SelectItem`、`SelectItemText`，用 `default-value` 设置默认值（例如 `apple`）。
9. 自定义触发元素：给 `DialogTrigger` 加 `as-child`，内部放自定义 `<button class="my-custom-button">Open</button>`，让触发器渲染为子元素并合并 props/行为。
10. 需要把组件渲染为子元素而不是外层 wrapper 时，用 `asChild` 合并 props 和行为。
11. 受控状态用 `v-model`；非受控状态用 `default*` props。
12. 按 Parts 组合组件：组件拆分为 `Root`、`Trigger`、`Content`、`Portal` 等部分，按层级组合。
13. 需要供动画库使用时，用 `forceMount` 把元素保留在 DOM 中。
14. 优化大列表时，在 `Combobox`、`Listbox`、`Tree` 中使用虚拟化虚拟滚动。
15. 需要从子组件访问组件上下文时，用 Context Injection。
16. 使用 v2.8.0 新增的 `Rating` 组件。
17. 使用 v2.8.0 中 `ScrollArea` 新增的 "glimpse" 滚动条模式。
18. 使用 v2.8.0 中 `PopperContent` 新增的 `hideShiftedArrow` prop。
19. 使用 v2.8.0 中 `TimeField` 新增的 `stepSnapping` 支持。
20. 处理 v2.8.0 破坏性变更：日期组件的 `weekStartsOn` 现在与 locale 无关，迁移时按此调整。
21. 处理 v2.7.0 虚拟化变更：`Listbox`/`Tree` 的 `estimateSize` 接受函数。
22. 使用 v2.6.0 暴露的 composables：`useLocale`、`useDirection`。
23. 使用 v2.7.0 中 `Select` 的 Content 上的 `disableOutsidePointerEvents` prop。
24. 使用 v2.6.0 中 `Toast` 的 `disableSwipe` prop。
25. 查阅 Reka UI Docs、GitHub、Nuxt UI、shadcn-vue 作为资源和参考实现。
26. 按 token 预算加载：基础约 350 tokens，`components.md` 索引约 100 tokens，每个组件约 50-150 tokens。

适用边界 · 注意事项

• 仅需要通用 Vue 模式时，改用 `vue` skill，不要用本经验。
• 为 Nuxt 构建基于 Reka UI 的有样式组件时，改用 `nuxt-ui` skill，不要用本经验。
• 项目不使用 Reka UI/Vue 3（例如 React、Vue 2 或其他组件库）时不适用。