aurora-admin
f1fbfc2ddb
Regression / regression (push) Canceled after 0s
## 品牌标识（本次会话） 起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」， 那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」， 移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边； 描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）； 顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0） 验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致； 两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
146 lines
8.2 KiB
Markdown
146 lines
8.2 KiB
Markdown
# 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` 为准：版本 v1.0.0、103/103 页面通过、1405 通过、0 失败、50 N/A、共 1455 条断言。
|
||
|
||
## 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
|