简介
Yi UI 是一个以 shadcn registry 形式发布的组件库，由 Travins 个人维护，官网是 yiui.dev。组件不打成 npm 包，而是用 shadcn CLI 把源码复制进你的项目，样式、结构、交互都可以直接改。
名字取自站点标志「易」（三道细斜杠是「日」，三道粗斜杠是「勿」）：既是「容易上手」，也是「随你改动」。
Yi UI 面向中文产品：文档用简体中文写，组件的默认文案（按钮、提示、读屏标签）是中文，排版按中文系统字体栈调过，装进中文项目基本不用再改文案。
视觉上统一使用「线条网格」语言：全宽横线、竖线容器、点阵分隔带，配合细边框、小圆角与克制的动效。
特点
- 源码归你 —— 通过 shadcn CLI 安装，组件、依赖的其他条目、需要的 CSS 变量会一并写入项目。
- Base UI 底座 —— 交互原语基于 Base UI，键盘操作、焦点管理与读屏语义开箱即用。
- 跟随主题 —— 所有颜色都取自主题变量：亮 / 暗模式加 14 套颜色主题，切换时组件自动变色。
- 方条控件系列 —— 数值滑块、分段选择、开关、色调、角度、二维拖拽板共用一套高度与外观，可以拼成参数面板，并一键把当前参数复制为 JSX。
- 动效有分寸 —— 进入视口才播放、离屏自动暂停、尊重「减少动态效果」。
- 预渲染友好 —— 页面在构建时全部预渲染；依赖测量或画布的组件在脚本加载前渲染同尺寸占位，不会出现空白或布局跳动。
- 对 AI 友好 —— 每篇文档都有 Markdown 版本，并提供
llms.txt 与 llms-full.txt。
快速开始
需要 React 19、Tailwind CSS v4，以及选择了 Base UI 底座的 shadcn 项目。
# 新建项目（已有项目去掉 -t / -n 两个参数）
pnpm dlx shadcn@latest init -t next -b base -p nova -n my-app
# 用完整地址安装任意组件
pnpm dlx shadcn@latest add https://yiui.dev/r/value-slider.json
想用更短的命令，在 components.json 里登记命名空间：
{
"registries": {
"@yiui": "https://yiui.dev/r/{name}.json"
}
}
pnpm dlx shadcn@latest add @yiui/value-slider
完整说明（文件落点、依赖、样式写入与常见问题）见安装文档。
组件
区块与模板
颜色主题
中性、石色、板岩三套灰阶基底，加红、橙、琥珀、青柠、绿、青绿、天蓝、蓝、紫罗兰、紫红、粉红 11 套彩色主题；彩色主题的按钮一律白字，对比度都在 4.5:1 以上。可以在主题页预览后复制 CSS 变量，或直接安装：
pnpm dlx shadcn@latest add https://yiui.dev/r/theme-blue.json
本地开发
git clone https://github.com/Travins/yi-ui.git
cd yi-ui
nvm use # Node 24（见 .nvmrc）
pnpm install
pnpm dev
| 命令 | 作用 |
|---|
pnpm dev | 启动开发服务器 |
pnpm build | 生产构建（pnpm start 本地预览） |
pnpm lint | 代码检查 |
pnpm registry:build | 生成 public/r/*.json 等 registry 产物 |
pnpm registry:lint | 检查 registry 条目的依赖、文件与书写规范 |
pnpm qa:shots <组件名> | 对构建产物截图验收（亮暗、颜色主题、窄屏、报错与溢出） |
pnpm qa:install [条目名…] | 本地安装、类型、构建与浏览器验收；支持 --fresh、--keep、--namespace |
pnpm qa:loading | 拦截脚本检查加载前的占位与空白 |
目录结构
content/ 文档与博客（MDX）
src/registry/ 对外发布的源码（唯一真源）
ui/ 组件
blocks/ 区块
templates/ 页面模板
examples/ 文档里的示例
src/components/ 站点自身的外壳、文档渲染、首页
src/styles/ 线条网格、颜色主题与文档样式
registry.json registry 清单
public/r/ 构建生成的 registry JSON
文档预览、代码展示与 public/r/*.json 都读取 src/registry/ 里的同一份源码。
技术栈
Next.js 16（App Router，部署在 Vercel）· React 19 · Tailwind CSS v4 · shadcn/ui · Base UI · Motion · Fumadocs（内容层）· Shiki · Recharts
参与贡献
欢迎提交 Issue 与 Pull Request，流程与规范见 CONTRIBUTING.md。
许可证
MIT © Travins
