介绍

Roost Design UI（@roost-design/ui）是一套开源的 Vue 3 组件库，提供 88 个组件、基于令牌的主题系统、内置国际化，以及带实时预览的文档站。

无论你是做管理后台、SaaS 产品还是内部工具，都可以直接使用统一的表单、浮层、数据展示与反馈能力。

特性

组件齐全

覆盖基础、表单、导航、数据展示、布局与反馈等 88 个组件，均支持 ESM 按需引入与 tree-shaking。

主题开箱即用

亮/暗色模式基于 --rd-* CSS 变量；通过 useTheme 切换主题，用 useDensity / useMotion 调整密度与动效，子树可用 RdConfigProvider 覆盖。

TypeScript 优先

基于 Vue 3 Composition API 与 TypeScript 编写，Props、Emits 与 locale 均有完整类型。

多种接入方式

支持全量注册、按名导入、按需子路径，以及配合 unplugin-vue-components 的 RoostDesignResolver——同一应用内建议保持一致。

文档即预览

每个组件自带 Markdown 文档与可交互 vue preview 示例，可在线浏览或本地启动文档站。

SSR 与元框架

兼容 Nuxt 3、Astro + Vue、Vite SSR 等场景；提供 @roost-design/nuxt 模块，详见 SSR 指南。

文档

https://roost-design.github.io/roost-design-ui/

| 章节 | 链接 | | --- | --- | | 快速上手 | 指南 | | 主题 | 主题 | | 全局配置 | 配置 | | SSR | Nuxt / Astro / Vite SSR | | 组件 | 目录 | | 更新日志 | 版本 |

安装

需要 Vue 3（推荐 3.5 及以上），以及能解析包 exports 的构建工具（Vite、webpack 5+ 等）。

pnpm add @roost-design/ui
# npm i @roost-design/ui
# yarn add @roost-design/ui

快速开始

全量注册并引入样式：

import RoostDesign from '@roost-design/ui'
import { createApp } from 'vue'
import App from './App.vue'
import '@roost-design/ui/styles.css'

createApp(App).use(RoostDesign).mount('#app')

按需引入（样式自动带入）：

import { RdButton } from '@roost-design/ui/button'
import { RdInput } from '@roost-design/ui/input'

应用级默认配置（语言、尺寸、浮层挂载点等）：

import { createRoostDesign, zhCN } from '@roost-design/ui'

createApp(App).use(createRoostDesign({ locale: zhCN })).mount('#app')

完整接入方式、Vite 解析器与主题 API 见 快速上手。

生态

| 包 | 说明 | | --- | --- | | @roost-design/ui | 组件、样式、主题与语言工具 | | @roost-design/nuxt | Nuxt 3 模块（样式、transpile、overlay 上下文） | | @roost-design/ui-mcp | 可选 MCP 服务，供 AI 客户端检索文档 |

参与贡献

欢迎提交 Issue 与 Pull Request。请先阅读 CONTRIBUTING.zh-CN.md。

维护者文档：开发指南 · 发版脚本

本地开发

pnpm install
pnpm dev              # 文档站 → http://localhost:5182
pnpm build            # 组件库 → dist/
pnpm build:docs:pages # GitHub Pages 构建
pnpm test
pnpm typecheck

许可证

MIT © Roost Design contributors