root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ee5d829a414b0413794c2f07a41e0e1cf257c60
aurora-admin/图标系统完成说明.md
T
aurora-admin f1fbfc2ddb
Regression / regression (push) Canceled after 0s
Details
feat(品牌标识): 几何 K 图标(favicon/顶栏标记/theme-color) + 并行会话成果入库 
## 品牌标识（本次会话）

起因：品牌此前没有任何图形标识 —— 唯一 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 未做部分）
2026-09-21 10:05:48 +08:00

9.6 KiB
Raw Blame History

任务完成说明 · 图标系统（IconSpec v1）

冻结规格：.design_library/kole-ui/icons/ICON-SPEC.md 完成日期：2026-09-20 ｜ 面向：Kole UI 设计系统（PC 103 组件 / 移动端 47 组件）

一 · 验收输出（原样粘贴命令输出，非转述）

1. 图标系统门禁（11 条断言）

$ node tools/verify-icons.mjs
图标系统静态门禁（ICON-SPEC.md §八）
  真源：registry 2576 · manifest 2576 · 别名 241 · core 151
  PASS  V1a manifest 内名字无重复 — 2576 个
  PASS  V1b manifest ↔ registry 双向一致 — 2576 个双向对齐
  PASS  V1c viewBox 例外表与 manifest 逐条一致 — 253 条例外
  PASS  V2 无 view-box 无效拼写残留（§二 修正 1） — 扫描 5 个产物文件
  PASS  V3 描边宽度全部 1.5（§二 修正 2）
  PASS  V4 core 层图标可渲染出非空 SVG — 151 个
  PASS  V4b core 计数自洽 — coreCount=151 / 实际 151
  PASS  V5 别名全部指向真实图标且不遮蔽（§三 3.2） — 241 条
  PASS  V6 各端 name 查找均能落到 registry（9 个端已注入）
  PASS  V7 分组覆盖率 ≥ 75%（§八 第 7 条） — 82.2% · 12 个分组 · 未分组 459
  PASS  V8 路径数字与源逐值一致（防隐式分隔粘连） — 比对 2576 个同源同名图标

未执行：把 core.js / aliases.json 重新从上游拉取核对（需联网，见 tools/fetch-icon-sources.mjs）

────────────────────────────
[OK] 图标系统门禁全部通过（11 条断言 · registry 2576 图标）
EXIT=0

2. 回归（八次连跑一致，铁律 §六）

$ REG_BASE=http://127.0.0.1:3401 node tools/run-regression.mjs     # ×8
run 1..8: passRate 100% | pages 103 (all-pass 103) | assertions 1464/1464 | N/A 50

$ REG_BASE=http://127.0.0.1:3401 node tools/run-mobile-regression.mjs  # ×8
run 1..8: passRate 100% | pages 47 (all-pass 47) | assertions 807/807 | N/A 10

3. 全部门禁（17 个脚本直接调用，exit code 实测）

verify-icons              exit=0      verify-cross-platform    exit=0
verify-mobile-isolation   exit=0      verify-families          exit=0
verify-uniapp             exit=0      verify-versions          exit=0
verify-uniapp-build       exit=0      verify-runtime-e2e       exit=0
verify-mobile-docs        exit=0      verify-theme             exit=0
verify-mobile-site        exit=0      verify-nav-responsive    exit=0
verify-playground         exit=0      verify-dark              exit=0
verify-examples           exit=0      verify-api-docs          exit=0
verify-i18n               exit=0

4. 浏览器实测（Chromium，真实渲染）

PC  frameworks/Icon.html           : 48 个 SVG 全部有 path，0 空；stroke-width 集合 = ['1.5']；view-box 残留 0；控制台错误 0
Mobile frameworks-mobile/Icon.html : 344 个 SVG 全部有 path，0 空；stroke-width = ['1.5']；类名全部 kole-m-* 前缀；控制台错误 0
全部 2576 个图标逐个渲染            : 产生控制台错误的图标 = 0
icon-preview.html                  : cells 2576 / rendered 2576；搜索 "search" → 24 个；控制台错误 0

5. 兼容性实测

移动端历史 9 名字形表：check/close/star/plus/minus/more → 命中 canonical；warn→warning、info→info-circle、arrow→chevron-right
Element UI 282 个历史图标名         : 280 可解析（余 2 个 `-left`/`-right` 是解析碎片，显式标记忽略）
PC 历史 icon prop（字形字符 '★'）    : 保留，name 优先

6. 离线可复现（移走缓存后重建）

$ mv .cache-icons /tmp/cache-backup && node tools/build-icons.mjs && node tools/verify-icons.mjs
图标总数 2576 ... OK
[OK] 图标系统门禁全部通过（11 条断言 · registry 2576 图标）

二 · 覆盖度（对用户点名的参考库）

参考库 图标数 本仓库覆盖 结果
TDesign Icons（线性 + 面性） 2356 2356 100%
Element Plus Icons 293 293 100%
Element UI Icons（历史名，字体图标） 282 280 99.3%（余 2 个是解析碎片名）
合计入库 2576

参考组件的图标功能对齐（用户点名）：

上游组件 图标相关能力 本仓库
TDesign TabBar / TabBarItem icon、badgeProps（图标角标）、subTabBar 图标提供 name；角标由既有 Badge 承担（既有设计，未改）
Element UI PageHeader 返回箭头、标题/副标题、extra 图标提供 back/chevron-left/arrow-left 三个语义名
TDesign Icon size 支持关键字与任意 CSS 值、onClick、class/style 透传 size 双模式；onClick 由端上事件承担

三 · 改动文件

新增（构建/门禁工具 5 个）

  • tools/fetch-icon-sources.mjs — 上游拉取 + 归一化（sha256 钉死；纯函数可无副作用 import）
  • tools/build-icons.mjs — 编译 manifest / registry / viewbox / core.js / ATTRIBUTION.md
  • tools/build-icon-aliases.mjs — 别名层（Element UI 282 名 + 移动端 9 名）
  • tools/inject-icon-table.mjs — 把 core 表注入 11 个端（支持 --check 幂等校验）
  • tools/verify-icons.mjs — 11 条静态断言

新增（数据产物，全部入库）

  • .design_library/kole-ui/icons/（ICON-SPEC.md / ATTRIBUTION.md / manifest.json / registry.json / sources.json / core.js / viewbox.js / aliases.json / element-ui-names.txt）
  • site/icons.json（文档站轻量索引）、site/icon-preview.html（图标预览页）

修改（端实现 11 个）

  • frameworks/Icon.{html,jsx,vue2.vue,vue3.vue,css}
  • frameworks-mobile/Icon.{html,jsx,vue2.vue,vue3.vue,uniapp.vue,css}

修改（站点与文档）

  • site/app.js（图标组件页挂「图标预览」入口）、site/i18n.js（+2 条双语）、 package.json（+3 个 script）、CHANGELOG.md、ROADMAP.md（+3 个衍生任务包）、.gitignore（忽略 .cache-icons/）

四 · 规划偏差

ROADMAP/任务书写的 实际的 原因
「覆盖他们全部拥有的 icon」预期一次性实现 分两层：全部 2576 个入库，其中 151 个 core 内联、其余按需加载（standard 1993 / extended 432） 实测全量路径数据 670KB；全内联等于每页 +670KB，违背性能预算。分层是缩量不缩覆盖 —— 2576 个全部可渲染
frameworks/Icon.css 作样式端应含图标表数据 数据端是 4 个（html/jsx/vue2/vue3），css 不含数据 注入器的 FILES 表不含样式文件；样式来源是 CSS 令牌而非图标表
计划用「11 个端各抄一份表」 改为单一真源 + 注入标记块 11 份手抄必然漂移，且漂移不报错（表现为某端图标空白）

五 · 发现的新问题

已在本任务内修复（自测发现，非外部报告）

  1. 构建期把坐标改错（数据损坏，静默） q-13.005.48-22.5 是三个数（-13.005、.48、-22.5，SVG 允许隐式分隔）。 把 -13.005 舍成 -13 后，后面的 .48 粘成 -13.48 —— 另一个坐标，图形画错且不报错。 实测踩到 Element Plus 的 quartz-watch。 修法：有小数位的数输出至少留 1 位小数；optimizePath 内复核数字序列。 防复发：新增门禁 V8，并做变异测试（重新注入该 bug → V8 FAIL 数字个数 461 ≠ 源 462）。

  2. 非 <path> 图形被静默丢弃 解析器只认 <path d>，而上游 36 个文件用 <circle> / <ellipse>（TDesign 的 circle / round / brightness / image 等）。这些图形被丢弃，图标"渲染成功"却是空的。 修法：解析 circle/ellipse 并换算成 path arc。 结果：2574 → 2576 个图标，TDesign 覆盖升至 100%。 是覆盖率审计（对三家参考库逐名比对）发现的，不是回归 —— 回归测不出"少了一个图标"。

登记为 ROADMAP 衍生任务包（不在本任务顺手修，遵守 §三「禁止范围蔓延」）

  • S8-P1 verify-emits-parse.mjs 的文件数期望值陈旧（硬编码 158 = 79×2，实际 103×2=206）。 本次之前就存在（git show HEAD: 确认该文件 HEAD 上就是 158，本任务未触碰）。
  • S8-P2 verify-cross-platform.mjs 把注入的图标数据表误判为组件类名（540 条 diff 里 533 条是噪声）。 是冻结规格「数据内联进端文件」的必然结果 —— 修法是让门禁学会跳过数据块，判据不放宽。
  • S8-P3 组件5.txt 声明的 47 个工具/模板组件里 46 个从未实现（本次只补了 IconPreview）。 含一个需要用户拍板的决策点：这批组件走 frameworks/ 正式组件（103 → 149，全部门禁基线跟着动） 还是 site/ 工具页（本次 IconPreview 走的是后者）。

六 · 遗留阻塞（不隐瞒）

项 状态 说明
mp-weixin / app-plus 的遮罩渲染 未验证 uni-app 端用 CSS mask 承载字形（小程序无 DOM/内联 SVG）。H5 目标已实测（着墨率 0.052 vs 无遮罩 1.000）；小程序端需真机或开发者工具复核，仓库门禁只覆盖静态与编译。已登记进契约 unknowns
verify-emits-parse 1 条既存 FAIL 见 S8-P1，非本任务引入
组件5 的 46 个组件 未实现 见 S8-P3，需先定第 5 节那个决策点

七 · 回归结论

PC 100%（1464/1464，103 页）· 移动端 100%（807/807，47 页）· 八次连跑一致 · 0 超时 17 个门禁脚本全部 exit=0（唯一 FAIL 是既存的 verify-emits-parse，已证明非本任务引入）

Reference in New Issue View Git Blame Copy Permalink