@yoka-ui/ui

企业级 React 组件库，提供开箱即用的 UI 组件、业务组件、主题封装和布局方案。
技术栈：React 19 / 18.3.1+ · antd 6 · TypeScript · Less · ECharts · CodeMirror · TipTap

目录

• 安装与使用
• 使用规范
• 本地开发
• 组件文档构建
• Docker 部署（跳板机执行见 DEPLOY.md）
• 发布 npm 包
• React 版本兼容性
• 组件列表
• AI / 助手文档
• 贡献指南

安装与使用

🆕 从零新建

当前没有可用的 React 项目，只是想试用 / 搭个 Demo：

1. 把 For Agents 页 的 prompt 复制给 AI Agent，让它带你走完建 Demo、装包、跑起来的全部步骤；或先下载 skills.zip 装好 Skill 再让 Agent 接手
2. 完整手动步骤（CRA 脚手架、Less/craco 配置）见包内 ai/README.md「教程 A」

➕ 已有项目增量开发

已有 React 项目，只是要接入组件库：跳过脚手架，直接执行下面「安装组件库」「引入样式」「基础用法」三步；AI Agent 接入见下方「（推荐）给 AI Agent 接入组件库」，或同样可以把 For Agents 页 的 prompt 贴给 Agent、下载 skills.zip 装 Skill。

安装组件库

# pnpm（推荐）
pnpm add @yoka-ui/ui

# 或 npm
npm i @yoka-ui/ui

引入样式

在应用入口引入一次：

import "@yoka-ui/ui/dist/index.less";

基础用法

import { YkButton, YkCard } from "@yoka-ui/ui";
import "@yoka-ui/ui/dist/index.less";

function App() {
  return (
    <YkCard title="示例">
      <YkButton type="primary">点击我</YkButton>
    </YkCard>
  );
}

（推荐）给 AI Agent 接入组件库

完整步骤见包内 ai/README.md（仓库开发期同路径）。安装后入口：node_modules/@yoka-ui/ui/ai/；Skill 发布目录：dist/yoka-ui/skill/。

摘要：

1. pnpm add @yoka-ui/ui，入口引入 import '@yoka-ui/ui/dist/index.less'
2. 配置 MCP（无需克隆源码）：npx -y @yoka-ui/mcp
3. 复制 Skill：cp -R node_modules/@yoka-ui/ui/dist/yoka-ui/skill .cursor/skills/yoka-ui
4. 合并 ai/AGENTS.md 到业务仓库 Agent 约定

包内 Agent 索引：llms.txt、ai/COMPONENTS.md、components.manifest.json；单组件契约为 dist/es/**/<Name>/<Name>.docs.md。

（可选）配置 Cursor rules

在项目的 Cursor rules 中创建文件 yoka-ui.mdc：

---
description: 使用 @yoka-ui/ui 时的导入与文档约定
globs: "**/*.{ts,tsx}"
alwaysApply: false
---

# @yoka-ui/ui

- **导入**：仅从 `@yoka-ui/ui` 做**具名** `import`，勿使用未在导出表中出现的符号。
- **导出清单（权威）**：`node_modules/@yoka-ui/ui/llms.txt` 与 `ai/COMPONENTS.md`。
- **LLM / 助手入口**：`llms.txt`；接入说明见 `ai/README.md`；Skill 从 `dist/yoka-ui/skill` 拷贝。
- **API**：先查 `*.docs.md` + Skill `ROUTING.md` + MCP，勿臆造 API。
- **全局样式**：`import '@yoka-ui/ui/dist/index.less'`。

使用规范

导入规则

仅从包入口做具名导入，禁止深路径导入：

// 正确 ✅
import { YkButton, YkCard, YkProTable } from "@yoka-ui/ui";

// 错误 ❌
import { YkButton } from "@yoka-ui/ui/es/button";      // 深路径导入
import { NonExistentComponent } from "@yoka-ui/ui";     // 臆造符号

样式引入

在应用入口引入一次：

import "@yoka-ui/ui/dist/index.less";

组件选用优先级

YkPro* (Pro 组件) → Yk* (基础组件) → antd 原生

• 表单优先使用 YkProForm* 系列
• 表格优先使用 YkProTable / YkTableTheme
• 筛选列表优先使用 YkModCommonFilter

权威导出清单

以 @Docs-yoka/exports.generated.md 为准，该文件由脚本根据 src/index.tsx 自动生成：

node_modules/@yoka-ui/ui/@Docs-yoka/exports.generated.md

修改导出后请执行 pnpm generate:yoka-llms 刷新（发版时 prepack 会自动执行）。

本地开发

面向本仓库贡献者。环境要求：Node.js >= 18，pnpm >= 9（与 package.json engines / Docker 内 pnpm@9 一致）。

pnpm install          # 会触发 prepare：husky + dumi setup
pnpm dev              # 文档站热更新，默认 http://localhost:6006
pnpm lint             # tsc --noEmit + biome lint（src / tests）
pnpm lint:ts          # 仅类型检查
pnpm test             # vitest run
pnpm test:coverage    # 覆盖率（CI 同脚本）

日常命令速查

| 命令 | 说明 | | --- | --- | | pnpm dev | 先生成 site llms、同步侧栏，再 PORT=6006 dumi dev | | pnpm clean | 删除 dist/、docs-dist/ 与 .dumi/ | | pnpm build | clean + build:lib（组件库发布产物 → dist/） | | pnpm build:lib | father 构建 + 生成 index.less | | pnpm build:docs | 构建 dumi 文档站（→ docs-dist/，含 /skills.zip；Docker 部署前由宿主机生成） | | pnpm generate:yoka-llms | 刷新 @Docs-yoka 导出表 | | pnpm generate:ai-docs | 生成组件 AI 文档 | | pnpm sync:ai-kit | 同步 AI Skill 到各 IDE / public 目录 | | pnpm test:ai-pack | 全量 AI 文档校验（CI 门禁） | | pnpm test:ai-docs-smoke | AI 文档快速冒烟测试 | | pnpm release | changeset version 后执行 pnpm build |

注意： 组件库产物在 dist/（build / prepublishOnly）；文档站产物在 docs-dist/（build:docs / Docker）。二者已分离，可同工作区并存。

组件文档构建

文档基于 dumi，脚本为 build:docs（与 CI build-docs job、跳板机宿主机构建一致）：

1. scripts/sync-ai-kit.cjs → 同步 Skill 镜像并生成 public/skills.zip
2. scripts/sync-docs-sidebar.cjs → site/sidebar.generated.json
3. scripts/generate-site-llms.cjs → public/ 下 llms 产物
4. dumi build → 静态站点（outputPath: docs-dist，含 /skills.zip）
5. 再次 generate-site-llms.cjs --output docs-dist → 把 llms 写入站点产物目录
6. scripts/verify-docs-dist-assets.cjs → 校验 llms*.txt / design.md / skills.zip 均在 docs-dist/

pnpm build:docs
# 产物目录：docs-dist/
# 本地预览静态站（需已安装 serve，或 npx）：
npx serve docs-dist -l 6006

本地联调组件 Demo 优先用 pnpm dev；验证生产构建时再跑 pnpm build:docs。

Docker 部署

跳板机上怎么执行，直接看根目录 DEPLOY.md（复制命令即可）。

摘要：

| 类型 | 端口 | 要点 | |------|------|------| | docs（默认） | 6001 | 宿主机生成 docs-dist/，镜像只 serve；平台 linux/amd64 | | mcp | 3001 | 独立更新；用 /health 看 capability=full（默认挂 /root/yoka-ui） |

脚本入口：deploy.sh（./deploy.sh -h）。详细参数、环境变量与手写 docker 命令仍可用该脚本帮助信息。

发布 npm 包

与文档部署无关，写入的也是 dist/，请单独执行：

pnpm build                 # 或依赖 prepublishOnly
# prepublishOnly：sync-ai-kit → check → clean → build:lib
# prepack：generate:yoka-llms → sync-ai-kit → check
pnpm publish --access public

React 版本兼容性

@yoka-ui/ui 支持 React 18.3.1+ 和 React 19，peer 依赖 antd >= 6。

| React 版本 | 说明 | | --- | --- | | 19.x | antd 6 已原生适配，无需 @ant-design/v5-patch-for-react-19 | | 18.3.x | 开箱即用，无需额外操作 |

若业务仍锁定 antd 5，按 antd 官方说明自行打补丁。

组件列表

所有组件从 @yoka-ui/ui 具名导入，导出符号以 src/index.tsx 为准。完整清单见 @Docs-yoka/exports.generated.md。

基础组件 (src/base/)

| 组件 | 说明 | | --- | --- | | YkButton | 按钮组件 | | YkCard | 卡片组件 | | YkCheckbox | 复选框 | | YkRadio / YkRadioGroup | 单选组 | | YkRadioBtnSpecial | 异形单选按钮组 | | YkSwitch | 开关 | | YkSelect | 选择器 | | YkSegmented | 分段控制器 | | YkTabs | 标签页 | | YkTooltip | 文字提示 | | YkTooltipRadioGroup | 带提示的单选组 | | YkPagination | 分页器 | | YkSpin | 加载中 | | YkStatistic | 统计数值 | | YkDescriptions | 描述列表 | | YkLabelSelect | 标签选择器 | | YkLogicOperator | 逻辑运算符 | | YkBasicTitle | 基础标题 | | YkBasicHelp | 基础帮助 | | YkArcCheckbox | 弧形复选框 | | YkAutoTransfer | 自动穿梭框 | | YkTreeTransfer | 树形穿梭框 | | YkClock | 倒计时时钟 | | YkCommonTable | 通用表格 | | YkContainerHide | 容器隐藏 | | YkCreateBtn | 创建按钮 | | YkDateRangePicker | 日期范围选择器 | | YkDebounceInput | 防抖输入框 | | YkErrorBoundary | 错误边界 | | YkGlassSegmentedRadio | 玻璃拟态分段单选 | | YkMarkdown | Markdown 渲染 | | YkModLoading | 模块加载 | | YkMultipleSelect | 多选组件 | | YkNumericInput | 数字输入框 | | YkPageTip | 页面提示 | | YkRangeDateWithVS | 日期范围 + 对比 | | YkRangeTimeWithRecent | 时间范围 + 最近 N 天 | | YkRefreshButton | 刷新按钮 | | YkScrollbars | 滚动条 | | YkSearchInput | 搜索输入框 | | YkSearchWithHistory | 带历史搜索 | | YkSkillsWriter | Skills 写入器 | | YkTextWithBg | 带背景文本 | | YkTextWithInput | 可编辑文本 | | YkTextWithToolTip | 带提示文本 | | YkButtonRadioWithInfo | 带说明按钮式单选 | | YkButtonWithProgress | 带进度按钮 |

布局组件 (src/layout/)

| 组件 | 说明 | | --- | --- | | YkContainer | 页面容器（sticky 页头 + 内容区留白） | | YkDrawer | 抽屉（四向 placement） | | YkFlexGrid | 响应式栅格 | | YkSectionCard | 分区卡片 | | YkSideMenu | 侧边菜单 |

主题组件 (src/theme/)

| 组件 | 说明 | | --- | --- | | YkInputTheme | 输入类组件主题封装 | | YkTableTheme | 表格主题样式封装 |

业务组件 (src/business/)

| 组件 | 说明 | | --- | --- | | YkAiChat | AI 对话组件 | | YkEditor | 富文本编辑器（TipTap） | | YkEmpty | 空状态 | | YkLoginModule | 登录组件（扫码 / 短信验证码） | | YkModCommonFilter | 通用筛选器 | | YkPorjectSelect | 项目选择器 | | YkSqlEdit | SQL 编辑器（CodeMirror 6） | | YkTipDrawer | 提示抽屉 | | YkArea / YkLine | 面积图 / 折线图（ECharts） | | YkBar / YkBarProperty / YkBarTotal | 柱状图系列 | | YkPie / YkPieProperty / YkPies | 饼图系列 |

Pro 组件 (src/pro/)

企业级 Pro 组件，内化自 @ant-design/pro-components，统一以 YkPro 前缀暴露。

| 组件 | 说明 | | --- | --- | | YkProTable | 高级表格 | | YkProForm | 高级表单 | | YkProLayout | 高级布局 | | YkProCard | 高级卡片 | | YkProDescriptions | 高级描述列表 | | YkProList | 高级列表 | | YkProProvider | 全局 Provider | | YkProConfigProvider | 配置 Provider | | YkProSkeleton | 骨架屏 | | YkProField | 字段组件 | | YkProPageContainer | 页面容器 | | YkProPageHeader | 页面头部 | | YkProBreadcrumb | 面包屑 | | YkProFooterToolbar | 底部工具栏 | | YkProGridContent | 网格内容 | | YkProSettingDrawer | 设置抽屉 | | YkProStatisticCard | 统计卡片 | | YkProCheckCard | 可选卡片 | | YkProLightFilter | 轻量筛选 | | YkProQueryFilter | 查询筛选 | | YkProDrawerForm | 抽屉表单 | | YkProModalForm | 模态框表单 | | YkProStepsForm | 分步表单 | | YkProLoginForm | 登录表单 | | YkProDragSortTable | 拖拽排序表格 | | YkProEditableTable | 可编辑表格 | | YkProTableDropdown | 表格下拉菜单 | | YkProBaseForm | 基础表单 | | YkProBetaSchemaForm | Schema 表单 | | YkProFormCascader | 级联选择 | | YkProFormCheckbox | 复选框表单项 | | YkProFormDatePicker | 日期选择表单项 | | YkProFormDateRangePicker | 日期范围表单项 | | YkProFormDateTimePicker | 日期时间表单项 | | YkProFormDependency | 表单项依赖 | | YkProFormDigit | 数字表单项 | | YkProFormGroup | 表单项分组 | | YkProFormItem | 表单项 | | YkProFormList | 表单列表 | | YkProFormMoney | 金额表单项 | | YkProFormRadio | 单选表单项 | | YkProFormRate | 评分表单项 | | YkProFormSelect | 选择表单项 | | YkProFormSlider | 滑块表单项 | | YkProFormSwitch | 开关表单项 | | YkProFormText | 文本表单项 | | YkProFormTextArea | 文本域表单项 | | YkProFormTimePicker | 时间选择表单项 | | YkProFormTreeSelect | 树选择表单项 | | YkProFormUploadButton | 上传按钮表单项 | | YkProFormUploadDragger | 拖拽上传表单项 |

AI / 助手文档

组件库为 AI Agent 提供了一整套文档和工具，便于 LLM 在编码时准确使用组件：

• 入口索引：根目录 llms.txt — 导航 + 使用约定
• 组件索引：ai/COMPONENTS.md；单组件契约 *.docs.md（发布后在 dist/es/**）
• 具名导出表：@Docs-yoka/exports.generated.md
• MCP：@yoka-ui/mcp（suggest_component / get_component_props / get_yoka_token / get_component_semantic / prompts；详见 ecosystem/yoka-ui-mcp/README.md）
• Skill：SSOT ai/skill/ → 发布 dist/yoka-ui/skill/
• Agent 约定：ai/AGENTS.md

安装 npm 包后路径：node_modules/@yoka-ui/ui/（ai/、llms.txt、components.manifest.json、@Docs-yoka/、dist/yoka-ui/skill、dist/es/**/*.docs.md）。

贡献指南

开发流程

1. 克隆仓库后执行 pnpm install
2. 使用 pnpm dev 启动文档站进行开发
3. 组件代码在 src/ 目录下，按分类存放：
   • src/base/ — 基础组件
   • src/business/ — 业务组件
   • src/layout/ — 布局组件
   • src/theme/ — 主题组件
   • src/pro/ — Pro 组件
   • src/provider/ — Provider 组件
4. 新增或修改组件后，运行 pnpm test 确保测试通过
5. 更新导出后执行 pnpm generate:yoka-llms 刷新导出表

代码规范

• TypeScript：strict: true，target: es2022，moduleResolution: bundler
• 格式化：Biome（2 空格缩进、单引号、分号、尾逗号、LF 换行、120 列宽），配置见 biome.json
• 编辑器：EditorConfig（src/ 下 2 空格、LF、UTF-8），配置见 .editorconfig
• 提交检查：Husky + lint-staged（提交前自动 biome check --write）
• 组件 Props：新公共 prop 必须写 JSDoc（供 generate:ai-docs 抽取）；可辨状态用联合类型，禁止 any
• 命名：组件统一 Yk 前缀（YkButton、YkProTable），目录名与导出名一致

提交规范

遵循 Conventional Commits，由 @commitlint/config-conventional 校验：

| 类型 | 说明 | | --- | --- | | feat | 新功能 | | fix | Bug 修复 | | docs | 文档更新 | | style | 代码格式调整 | | refactor | 重构 | | perf | 性能优化 | | test | 测试相关 | | chore | 构建/工具变动 | | revert | 回退提交 | | build | 构建系统 | | ci | CI 配置 |

规则：header 最长 100 字符，body 前需空行。

发布流程

发版前会自动执行一系列校验，确保产物完整性：

# 1. 版本号变更 + 构建
pnpm release          # changeset version → pnpm build

# 2. 手动发布到 npm
pnpm publish --access public
# 发布前自动触发：
#   prepublishOnly：generate:yoka-llms → sync:ai-kit → check:ai-kit → check:ai-docs → check:four-piece → clean → build:lib
#   prepack：generate:yoka-llms → sync:ai-kit → check:ai-kit → check:ai-docs → check:four-piece

许可证

MIT