aurora-admin
5ee5d829a4
本提交含两条并行工作线，因互相咬合（package.json scripts、regression.yml、 npm run build 链）无法按文件干净拆分，故合并为一次自洽提交。 ## 详情页减重（本轮主任务：修复「AI 干太重」） - 导航收敛：宽屏只用右侧目录、≤1200px 只用页内 sticky 导航，纯 CSS 媒体查询 实现（不引入 JS 宽度监听）。此前两套导航同时可见，active 状态互相打架。 - 入口去重：标题区由「查看示例/在线测试/契约 JSON」三个减为「在线测试」一个； 契约 JSON 归入实现资源；删除示例底部重复的「在线测试」。 - 示例工具栏：删除与目录锚点重复的示例下拉选择器；「全部展开代码」只在 示例数 >1 时出现（103 个组件里 49 个仅 1 个示例，此前恒显示）。 - 重复文案：示例区两句同义导语合并为一句。 - 首页 CTA 由 5 个减为 2 个（浏览组件/快速开始），测试总览入口挂到已有的 通过率统计卡上，不再另占 Hero 按钮。 - 统一详情取数：抽出 fetchDetail/loadDetail 作为 details/*.json 的唯一路径， FAQ 不再自行 fetch 一遍，与组件页共用缓存与失败兜底。 ## i18n - 删除 12 组重复键（含整段 FAQ 说明），字典 604 → 585 唯一键。 - 删除本次改动产生的 6 个死键。 - verify-i18n.mjs 新增 `unique dictionary keys` 断言：重复键在对象字面量里 是静默的后值覆盖，此前无从发现；现由门禁拦住。 ## 文档事实修正（实测为准） - TESTING/CONTRIBUTING：79 → 103 组件；旧断言数改为回指 tests/report.json。 - PLATFORMS：移动端 108 文件/18 端 → 282 文件/47 端；契约 5 → 47； 令牌 17 → 15；uni-app SFC 21 → 50。 - AGENTS：断言 1405/18 页 → 1464/103 页（PC）、807/47 页（移动端）。 - package.json：YOUR-ACCOUNT 占位 → gitea 实址与 kole-ui.mymoyu.top。 ## 品牌标识（并行会话成果，一并入库） - brand-mark.json 收归真源，build:brand 生成 favicon 与单色 SVG； PC 与移动端共用资产，verify:brand 24 条断言。 - regression.yml 增加 verify:brand 步骤。 ## 门禁与验收 新增工具：verify-component-page.mjs（86 条真实浏览器断言，随详情页改造同步 更新为「只允许一套导航可见」）、verify-brand-mark.mjs、lib/i18n-dead-keys.mjs （只读诊断）。 回归：PC 100%（1464/1464，103 页，N/A 50）· 移动端 100%（807/807，47 页）。 门禁：component-page 86 · i18n 17 · brand 24 · routes all · smoke all · theme OK · isolation 31 · nav all · examples 9 · api-docs 10 · mobile-docs 12。 已知未做：i18n 另有约 44 条历史死键（非本次产生），已记为 ROADMAP S8-P6； 顶栏与悬浮区的两个主题入口为刻意设计（verify-theme 断言其互斥），未删。
Kole UI Design System
理性、高效、克制的 B 端中后台设计系统：103 个组件全量契约 × 4 个运行端 + CSS 资产（H5 / React / Vue 2 / Vue 3 / CSS），品牌主色 #2F54EB，全部色值取自 kole-* CSS 变量令牌，零运行时依赖。
在线入口
- 组件文档站：
site/index.html（GitHub Pages 部署后为仓库首页自动跳转） - 机器可读数据 / llms.txt：
site/llms.txt·site/data.json - 文档站支持简体中文 / English 切换，语言偏好保存在
localStorage['kole-lang']，切换时保留当前路由与技术栈选择；运行npm run verify:i18n做静态覆盖检查，运行npm run smoke:site做浏览器冒烟验收。
主题模式与 RTL 现状
文档站和 ThemeSwitcher 支持 light、dark、auto 三种模式。部分组件样式已迁移到 CSS 逻辑属性，可在宿主页面用 dir="rtl" 做定向验证；RTL 目前属于已纳入验证与迁移范围的现状能力，不代表 103 个组件已经完成全量 RTL 视觉验收。
无障碍（A11y）目前是自动化结构断言基线：覆盖键盘可达、焦点环、ARIA、对比度和 token 使用等规则；当前基线不等同于完整 WCAG 合规声明，屏幕阅读器、焦点顺序、动态播报和 200% 缩放仍需人工或辅助技术验收。
目录结构
├─ index.html # Pages / Docker 入口（重定向到 site/）
├─ sitemap.xml # 站点地图
├─ site/ # 文档站（纯静态，无构建依赖）
│ ├─ index.html / app.js / style.css / data.js / data.json
│ ├─ components/<slug>.html # 每组件静态薄壳（SEO 可爬入口）
│ ├─ details/<slug>.json # 按需加载的完整契约与规格详情
│ ├─ sources/<slug>/* # 文档站试玩与源码查看所需源码
│ └─ llms.txt
├─ frameworks/ # 103 组件 × 4 运行端 + CSS 资产
├─ tests/ # 测试页与当前回归报告
├─ tools/ # 回归、冒烟和静态验证脚本
└─ .design_library/kole-ui/
├─ components/index.json # 103 个全量契约的权威映射
├─ components/<slug>.json # 组件设计契约
├─ colors_and_type.css # 设计令牌
└─ components.css # 聚合组件样式
快速使用
从私有 npm 源安装（推荐）
本包已发布到自建 Gitea 的 npm registry（gitea.mymoyu.top），匿名可读，无需登录。
推荐用 scoped 包名 @root/ui —— 只需在项目 .npmrc 写一行，其余依赖仍走公共源：
# .npmrc
@root:registry=https://gitea.mymoyu.top/api/packages/root/npm/
npm install @root/ui
也可用非 scoped 别名（内容完全相同），但要显式指定源：
npm install chunyu-ui --registry=https://gitea.mymoyu.top/api/packages/root/npm/
三个可互换的发布名：
@root/ui（推荐，支持 .npmrc 一行配置）、chunyu-ui、aurora-admin-design。内容一致。⚠️ 最后一个名字是 v1.4.x 的旧包名，也是源上当前真实存在的那个 —— 仓库自 v2.0.0 起改名为
kole-ui（package.json.name），但尚未以新名重新发布到该源（实测源上无kole-ui）。在新的发布动作完成前，安装请用上表中实际存在的三个名字之一。
装好后在框架项目里按端引入（令牌必须先引，否则组件渲染但样式丢失）：
// Vue 3 —— main.js
import '@root/ui/tokens/tokens.css';
import * as Kole from '@root/ui/vue3';
Object.entries(Kole).forEach(([name, comp]) => app.component(name, comp));
// React —— main.jsx
import '@root/ui/tokens/tokens.css';
import { KoleButton, KoleTable } from '@root/ui/react';
Vue 2 用 @root/ui/vue2（需构建链具备 SFC 编译能力）。组件以 .vue / .jsx 源码发布，由你项目的构建链编译；react / vue 是 peerDependencies，按用到的端安装即可。
⚠️ 导入名随版本不同：源上已发布的包是 v1.4.x，导出名是
AaButton/AaTable（本仓库 v2.0.0 起统一改为KoleButton/KoleTable）。上面的示例写的是当前仓库的名字；如果你装的是源上那个旧版本，把Kole换回Aa即可。以实际装到的包入口文件为准。
不用 npm：直接引样式
<link rel="stylesheet" href=".design_library/kole-ui/colors_and_type.css">
<link rel="stylesheet" href=".design_library/kole-ui/components.css">
按端取用组件源码：frameworks/<Prefix>.{html,css,jsx,vue2.vue,vue3.vue}。四个运行端是 H5、React、Vue 2、Vue 3；CSS 是配套样式资产，不另计为运行端。
本地开发与验证
需要 Node 20+。仓库没有运行时 npm 依赖，Playwright 仅用于 CI/本地验证。
npm ci
node site/dev-server.js # http://127.0.0.1:3311/site/
npm run verify:i18n
node tools/verify-site-routing.mjs
node tools/verify-site-routes.mjs # 无 # 路由的浏览器级验收（深链/刷新/前进后退/旧 # 链接/file:）
node tools/verify-cross-platform.mjs
npm run smoke:site
node tools/run-regression.mjs
verify-cross-platform 会报告四端结构差异，但差异是信息项，不会把历史差异升级成失败；组件总数异常或文件读取错误会阻断检查。回归数字不在本文维护，以 tests/report.json 为准（当前：103/103 页面通过、1464 通过 / 0 失败 / 50 N/A，共 1514 条断言）。
Docker
docker compose up --build
服务只发布到本机 127.0.0.1:3311，健康检查地址为 http://127.0.0.1:3311/healthz。
部署（GitHub Pages）
GitHub Actions 会把文档站运行所需的最小静态包组装到 site-dist/ 后发布，不再上传整仓。发布包保留 site/、sources/、details/、data、样式、i18n、logger、组件 shell、框架 demo 及必要设计令牌/契约；排除 Git 元数据、测试页主体、全量规范源、workflow、配置和报告（首页使用的 tests/report.json 摘要除外）。
仓库 Settings → Pages → Source 选 GitHub Actions；推送 main 后自动部署。发布包在根目录多放一份 site/index.html 的副本作 404.html —— Pages 没有重写规则，深层路由靠它接住。
文档站路由（无 #）
路由走 History API，路径就是 URL 路径：/site/overview、/site/component/button/h5，站内跳转由 pushState 局部渲染，不再整页刷新。
- 深层路径磁盘上没有对应文件，由服务器回落到 SPA 壳：
nginx.conf的location /site/+site/dev-server.js的isSpaRoute+ Pages 的404.html三处必须同时存在，缺一个就会出现「点得进去、刷新 404」。带扩展名的缺失资源仍回真 404，不会被回落吞成 HTML。 - 站点根由 URL 反推（取
pathname里第一段/site/），所以部署前缀可变（本地/nginx 是/site/，Pages 是/<repo>/site/）。代价是站点目录必须一直叫site—— 改目录名要同步改site/index.html顶部的内联脚本和site/app.js的SITE_BASE。 - 页面资源用绝对地址（
base + 'style.css'）写出，不能写静态相对路径：相对路径会被预扫描器按深层 URL 先白取一次（实测 2 个 404 + 2 条控制台报错，data.js还会被整份重下一次）。 - 旧链接
/site/#/component/button仍然可用：解析后replaceState成无#的地址，不留历史记录。
设计契约与 Agent 消费
site/data.json是对外承诺的一次请求全量数据源：meta、六大分类、设计令牌和 103 个组件。.design_library/kole-ui/components/*.json是 103 个组件契约，包含变体维度、使用要点、结构、不发明边界和未明示项。site/llms.txt汇总机器可读资源与使用规则（文档站的 AI 消费页已移除，机器入口保留在仓库文件层）。- 生成 UI 时：色值只取令牌，变体不超出契约
dims，unknowns项先澄清再生成。
版本
见 CHANGELOG.md。当前版本以 site/data.json.meta.version 为准（目前 v1.0.0）。
许可证
MIT © 2026 Kole UI