caomei-ui

一个基于 Vue 3 与 Reka UI 的自建组件库。组件与样式解耦，默认提供极简可用的样式（具名预设 minimal，缺省即它）并支持 100% 覆盖；主题切换与暗色模式开箱即用，同一套组件适配桌面端与移动端。

• 定位：替代多个下游项目中的 PrimeVue，规避 PrimeUI 商业许可风险
• 当前版本：0.6.0（npm latest），样式入口 caomei-ui/theme.css
• 阶段进展、组件清单与下一步方向见路线图、待办事项 与 Backlog
• 发布策略：本地手动发布，CI 自动发布暂缓；0.x 期间 API 与目录结构仍可能调整（冻结面见版本与兼容策略）

✨ 特性

• 组件与样式解耦：默认极简样式（预设 minimal，缺省），可完全通过 --caomei-* CSS variables 覆盖，不引入 Tailwind / UnoCSS。
• 主题与暗色模式：CSS variables + 语义化 token；支持 .dark / [data-theme="dark"] 与三套预设（data-preset：极简 minimal（缺省）/ caomei / momei）；系统跟随需显式开启（data-scheme="auto"）。
• 桌面与移动适配：单包响应式，不拆分移动端包。
• 单仓库单包：组件、样式、resolver、Nuxt 模块通过子路径导出，消费者只需安装一个包。
• 无障碍：基于 Reka UI 的 ARIA、键盘导航与焦点管理。

📦 依赖要求

• Node.js >= 20
• pnpm（版本以根 package.json 的 packageManager 为准）

🚀 安装

pnpm add caomei-ui

当前最新版本为 0.6.0（样式入口为 caomei-ui/theme.css；0.5.0 新增 CaomeiRichTextEditor 富文本编辑器封装（可选 peer 依赖 md-editor-v3）、把极简具名预设 minimal 设为缺省预设，并修复模态内浮层被遮挡的缺陷；0.6.0 修复 Tabs 激活指示条被裁剪与多余纵向滚动条、DataTable 排序指示条列宽跳动，并统一组件背景 / 阴影 token 与分组标签 / 折叠触发器可访问性），组件库以 Vue 3.5+ 作为 peer 依赖（需在项目中自行安装）。0.x 阶段 API 与目录结构在 1.0 前可能调整，冻结面见版本与兼容策略。

除 Vue 3.5+ 外，部分组件另有可选 peer 依赖（当前为 CaomeiRichTextEditor 的编辑器内核 md-editor-v3）：未使用这些组件的下游无需安装、也不受影响；使用前须自行安装（pnpm add md-editor-v3）。

需要参与开发或本地联调时，也可通过本地依赖（file: / link:）消费构建产物，步骤见本地联调。

📖 使用

按需引入（推荐）

import Components from 'unplugin-vue-components/vite'
import { CaomeiUiResolver } from 'caomei-ui/resolver'

export default defineConfig({
  plugins: [Components({ resolvers: [CaomeiUiResolver()] })],
})

全量引入

import { CaomeiButton } from 'caomei-ui'

组件样式随包自带（打包器按组件丢弃未使用的 CSS）；基础层（tokens / 暗色 / 预设）需显式引入 import 'caomei-ui/theme.css'，或走上面的按需引入（resolver 会自动注入）。

<template>
  <CaomeiButton variant="primary">按钮</CaomeiButton>
</template>

Nuxt 项目

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['caomei-ui/nuxt'],
  caomeiUI: {
    prefix: 'Caomei',
    darkMode: 'class',
    injectStyles: true,
    theme: { primary: '#2563eb' },
  },
})

组件、composables 与样式自动接入；选项见架构设计 §5。

模块基于 @nuxt/kit，该包声明为可选 peer 依赖：Nuxt 4 应用自带同名依赖、无需手工安装，非 Nuxt 消费者则不会安装它。模块要求 Nuxt 4。

主题定制

:root {
  --caomei-color-primary: #2563eb;
  --caomei-radius-md: 6px;
}

若自定义品牌色会作为实底或底色承载文字 / 图标，需同时覆盖对应 tone 的 -solid 与 -foreground（如 primary-solid / primary-foreground）（详见主题与样式 §4）。

完整用法见 快速上手。

🛠️ 开发

pnpm install        # 安装依赖
pnpm dev            # 启动 playground 开发环境
pnpm build          # 构建库产物（tsdown）
pnpm typecheck      # vue-tsc --noEmit
pnpm test           # 单元测试（Vitest）
pnpm test:e2e       # E2E（Playwright）
pnpm lint           # ESLint
pnpm lint:css       # Stylelint
pnpm lint:md        # Markdown（lint-md）
pnpm docs:dev       # 文档站开发
pnpm verify         # 运行全部质量门

🧱 技术栈

图标默认使用 @lucide/vue；@iconify/vue 作为字符串图标名的可选扩展按需引入。

📁 目录结构

src/
├─ components/    # 组件（kebab-case 目录 + kebab-case.vue）
├─ composables/   # useToast / useConfirm / useTheme / useLocale / provideLocale
├─ locale/        # 组件内建文案（10 语；预注册 zh-CN / en-US，其余按需引入）
├─ styles/        # tokens 与基础样式
├─ icons/         # 图标封装（@lucide/vue）
├─ resolver/      # unplugin-vue-components resolver
├─ nuxt/          # Nuxt 模块
├─ types.ts       # 共享类型
└─ index.ts       # 公共 API 导出
playground/       # 本地开发/演示环境（不发布）
docs/             # VitePress 文档站
examples/         # 集成示例（不发布）
test/             # 单元与 E2E 测试

组件目录与组件文件采用 kebab-case；组件对外名称使用 Caomei + PascalCase（如 CaomeiButton）。

📚 文档

• 快速上手
• 开发指南
• 发布指南
• 架构设计
• 组件设计
• 项目规范

🤝 贡献

欢迎贡献、提问或提出新功能！如有问题请查看 issues。提交前请阅读 贡献指南 与 开发规范。

💰 支持

如果觉得这个项目有用的话请给一颗 ⭐️，非常感谢。

🌟 Star History

📝 License

Copyright © 2026 CaoMeiYouRen. This project is MIT licensed. 第三方依赖许可见 THIRD-PARTY-LICENSES。