root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
f1fbfc2ddb577d01f44d1b1f707368bc2f34c0ae
aurora-admin/PLAN.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

8.5 KiB
Raw Blame History

Kole UI 组件文档体系 — 规划 / 路线图

项目：C:\Users\12914\Desktop\组件规范第一套 当前版本：1.0.0 · 品牌：Kole UI（主色 #2F54EB） 规划目标：在已有 79 个组件 × 5 端实现 的基础上，补齐「完整内容模块 / 日志 / 搜索 / 测试 / 路线图」五大体系，让这套组件库成为可对外交付、可被审计、可被检索、可被回归的产品级文档。

1. 现状盘点（2026-09-07 评估）

模块 已存在 评价 是否需要补
README.md / SKILL.md ✅ 品牌叙事 + Agent 入口齐备 否
colors_and_type.css / css.json / components.css ✅ 设计令牌 100% 覆盖 否
components/index.json + 6 个核心契约 ✅ 79 项实现已登记，6 核心含契约 否（扩展契约待补）
frameworks/ × 5 端 ✅ 79×5=395 文件 否
site/index.html + style.css + app.js ✅ Element 风格三栏 + Ctrl+K 搜索 + 主题定制 搜索增强、错误日志待补
site/dev-server.js ✅ 单文件 75 行 HTTP 服务 否
build-site.ps1 ✅ 生成 site/data.js 日志开关待补
组件测试页 ❌ 仅 6 个核心组件有 preview/*.html；73 个扩展无独立测试 必补
变更日志 CHANGELOG.md ❌ 没有 必补
路线图 / 计划 ❌ 没有（本文档填补） 必补
测试入口 / 测试计划 ❌ 没有 必补
贡献指南 CONTRIBUTING.md ❌ 没有 必补
系统日志（构建/搜索/渲染） ❌ console 散落 必补

2. 内容模块（Content Modules）— 完整组件文档应包含的 10 项

# 模块 落地位置 内容要点 状态
1 品牌与原则 .design_library/kole-ui/README.md 品牌叙事 / 设计原则 / Content Fundamentals ✅
2 设计令牌 colors_and_type.css + css.json 色彩/字体/间距/圆角/阴影/控件高度 ✅
3 核心组件契约 .design_library/kole-ui/components/*.json 变体维度 / 代表变体 / 使用要点 / 结构 / 解剖 / 不发明 / 未明示 ✅ 6 项；73 项扩展契约待补（计划 1.1）
4 规格批次映射 .design_library/kole-ui/components/index.json slug ↔ 规范文件 ↔ 实现前缀 ✅
5 全量预览 frameworks/<Name>.html 5 端展示 ✅
6 文档站首页/总览/快速开始/设计规范 site/app.js + site/style.css Element 风格布局 + 锚点目录 ✅
7 全局搜索 Ctrl+K 弹窗 (bindSearch) 中/英/slug 模糊匹配 ✅；搜索日志待补（计划 2.1）
8 主题定制器 悬浮工具 (theme-panel) 4 键覆盖 + 复制 CSS ✅
9 每个组件的测试页 tests/<slug>.html 交互断言 / 键盘可达 / 焦点环 / 状态矩阵 ❌ → 本轮补齐
10 变更日志 / Roadmap CHANGELOG.md / PLAN.md 版本化记录 + 计划 ❌ → 本轮补齐

3. 日志系统（Logging）— 应收集的四类事件

类别 来源 落盘 用途
构建日志 build-site.ps1 site/data.js 首行 + logs/build.log 缺失文件 / 无分类组件告警
渲染日志 site/app.js localStorage[kole-render-log] + 可选下载 首页/总览/详情/搜索加载耗时、缺失 iframe、脚本错误
搜索日志 bindSearch() localStorage[kole-search-log] 关键词、命中数、点击目标
测试日志 tests/<slug>.html（本轮新增） localStorage[kole-test-log] 每组件测试结果、失败项、堆栈

所有日志默认本地落盘（避免隐私问题），提供「导出」按钮 → 复制 JSON，方便提交 issue。

4. 搜索系统（Search）— 现有 + 增强

4.1 现有

  • 触发：Ctrl+K / 顶栏按钮
  • 字段：组件中文名 / 英文名 / slug
  • 上限：20 条
  • 排序：原顺序

4.2 本轮增强

能力 描述
分类过滤 Ctrl+K 弹窗内 chip 行，可只看某一类（如只看「反馈」类）
关键词高亮 命中字符 <mark> 包裹
模糊容错 子串匹配 + 大小写不敏感；支持中英文混输
搜索日志 记录每次 query、点击目标、毫秒级耗时
全局快捷键 Ctrl+/ 在页面内任意位置直接聚焦搜索（已 Ctrl+K 仍可用）

5. 测试系统（Per-Component Tests）— 范围与原则

5.1 原则

  • 零依赖：纯 HTML + 原生 JS + design tokens，可直接在浏览器打开
  • 可视化：每个组件独立 tests/<slug>.html，含三段：① 渲染快照 ② 交互用例 ③ 断言结果表
  • 可机器读取：每条断言在 DOM 上加 data-assert="<id>" 与 data-status="pass|fail"，便于 Playwright/Selenium 回归

5.2 通用测试矩阵（每个组件都跑这 8 项）

  1. 默认态渲染 —— 快照含核心节点
  2. 尺寸/类型变体 —— 大/中/小 / 主/次/危险…
  3. 状态覆盖 —— hover / active / focus / disabled / loading
  4. 键盘可达 —— Tab 进入、Space/Enter 触发、Esc 关闭
  5. 焦点环可视 —— focus-visible 不被覆盖
  6. ARIA 属性正确 —— role / aria-disabled / aria-expanded
  7. 对比度 ≥ 4.5:1（正文） / 3:1（大字号）
  8. token 一致性 —— 所有颜色取自 --kole-*，不硬编码

5.3 本轮落地

  • 79 个组件全部生成 tests/<slug>.html（脚本批量）
  • 顶部总入口 tests/index.html —— 79 个测试页的导航 + 通过率
  • run-tests.ps1 —— 本地一键构建测试目录（可扩展到 headless 跑通）

6. 路线图（Roadmap）

6.1 v1.0.0（当前）— 文档骨架就绪

  • ✅ 79 个组件 × 5 端实现
  • ✅ 设计令牌 100%
  • ✅ Element 风格文档站
  • ✅ Ctrl+K 搜索

6.2 v1.1.0（本轮）— 文档可被审计、可被回归

  • 🆕 tests/<slug>.html × 79
  • 🆕 tests/index.html 总览
  • 🆕 CHANGELOG.md v1.1.0
  • 🆕 CONTRIBUTING.md
  • 🆕 TESTING.md
  • 🆕 site/logger.js（构建/搜索/渲染日志）
  • 🆕 site/test-logger.js（测试日志）
  • 🆕 搜索增强：分类过滤 / 高亮 / 模糊容错
  • 🆕 run-tests.ps1 构建脚本

6.3 v1.2.0（未来）— 进阶能力

  • 给 73 个扩展组件补齐 components/<slug>.json 契约
  • 提供 site/data.json（无 JS 注入的纯 JSON，供爬虫/SSR）
  • 接入 Playwright headless 跑测试，输出 JUnit XML
  • 国际化 i18n：EN/JP 双语
  • 暗色主题 dark variant
  • 接入 Storybook 作为开发环境（可选）

7. 验收标准（本轮完成定义）

  • ✅ 每个组件有 tests/<slug>.html
  • ✅ tests/index.html 能列出全部 79 项并给出通过率
  • ✅ 文档站支持 Ctrl+K 搜索 + 分类过滤 + 高亮
  • ✅ CHANGELOG.md 记录 v1.1.0
  • ✅ PLAN.md（本文件）记录路线图
  • ✅ CONTRIBUTING.md 写明如何加新组件
  • ✅ TESTING.md 写明测试矩阵与执行方式
  • ✅ site/app.js 内置日志收集，可在控制台 koleLogger.export() 导出
  • ⚠️ 规划修正（2026-09-19 实测）：原「现有 site/dev-server.js 不破坏，原样保留」已不成立——该服务单个 GET /site/%00 即触发 ERR_INVALID_ARG_VALUE 未捕获异常并退出进程，已修复（NUL 双重拦截 + readFile try/catch + KOLE_PORT 开关）。见 tools/verify-dev-server.mjs。
  • ✅ 不修改 site/data.js（自动生成物）、不改 build-site.ps1 主流程

8. 不在本轮范围（显式排除）

  • ❌ 不写 React 单元测试（Jest/Vitest），保持零依赖
  • ❌ 不引入 npm 依赖
  • ❌ 不改 git
  • ⚠️ 规划修正（2026-09-19 实测）：原「不改 site/dev-server.js（已工作良好）」的立论被实测推翻（见 §7 同条），该文件已按缺陷修复；此后对其改动仍需跑全量回归。
  • ❌ 不动 frameworks/ 下的源码（只读引用）
  • ❌ 不重构 site/app.js 主体，只追加新文件 / 追加 hook
  • ❌ 不改 DSH harness settings / memory

9. 风险与对策

风险 对策
79 个测试页太大、构建慢 生成器脚本一次写完；后续增删组件只需重跑
测试页与展示页视觉脱节 复用 colors_and_type.css + components.css，保持同源
文档站日志带来隐私顾虑 仅落 localStorage，提供导出按钮，不发任何远程
搜索增强改动影响现有 Ctrl+K 走增量 hook，老逻辑保留
与 build-site.ps1 冲突 新增独立脚本 run-tests.ps1，不动 build 流程
Reference in New Issue View Git Blame Copy Permalink