root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
aurora-admin/README.md
T
aurora-admin 5ee5d829a4
Regression / regression (push) Canceled after 0s
Details
refactor(详情页+S8): 详情页减重(导航互斥/入口去重/i18n去重) + 品牌标识入库 
本提交含两条并行工作线，因互相咬合（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 断言其互斥），未删。
2026-09-22 23:56:05 +08:00

146 lines
8.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Kole UI Design System
理性、高效、克制的 B 端中后台设计系统：**103 个组件全量契约 × 4 个运行端 + CSS 资产**（H5 / React / Vue 2 / Vue 3 / CSS），品牌主色 `#2F54EB`，全部色值取自 `kole-*` CSS 变量令牌，零运行时依赖。
## 在线入口
- 组件文档站：[`site/index.html`](./site/index.html)（GitHub Pages 部署后为仓库首页自动跳转）
- 机器可读数据 / llms.txt：[`site/llms.txt`](./site/llms.txt) · [`site/data.json`](./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` 写一行，其余依赖仍走公共源：
```ini
# .npmrc
@root:registry=https://gitea.mymoyu.top/api/packages/root/npm/
```
```bash
npm install @root/ui
```
也可用非 scoped 别名（内容完全相同），但要显式指定源：
```bash
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`）。在新的发布动作完成前，安装请用上表中实际存在的三个名字之一。
装好后在框架项目里按端引入（**令牌必须先引**，否则组件渲染但样式丢失）：
```js
// 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：直接引样式
```html
<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/本地验证。
```bash
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
```bash
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](./CHANGELOG.md)。当前版本以 `site/data.json.meta.version` 为准（目前 v1.0.0）。
## 许可证
[MIT](./LICENSE) © 2026 Kole UI
Reference in New Issue View Git Blame Copy Permalink