Files

T

aurora-admin 382ca79b66 v1.4.0: 组件层全面令牌化（设计系统根基修复）

问题
- 79 个组件的 844 个颜色属性里，只有 2 个（0.2%）引用令牌，
  788 个（93.4%）硬编码 hex
- 后果：改令牌组件不跟着变、主题定制器对组件无效、For Agents 页写的
  「所有色值必须取自 au-* 变量」形同虚设
- 这是本项目第五次「声称≠实现」，且动摇了设计系统的根本

两层令牌化（此前只改了从未被加载的文件，走了弯路）
- 组件样式表 frameworks/*.css：915 处 / 78 文件
- 演示页内嵌 <style>（实际生效的样式层）：287 处 / 51 文件
- 内嵌样式层是决定性的：演示页只 link colors_and_type.css + 自己的 CSS，
  而多数页面把关键样式写在 <style> 块里 —— 只改 CSS 文件不生效

安全策略
- 只替换颜色属性值位置的 hex（color/background*/border*/outline*/fill/stroke）
- 跳过 rgba()/渐变/url() 复合值；不动 SVG 属性与 JS 数据（色板数组）
- 歧义色值按属性语义消解（#FFFFFF 作 color→text-inverse，作 background→card-bg）
- 幂等，可重复运行

补齐令牌语义（71 → 74）
- --au-color-text-tertiary #595959（规范未定义、实现补齐，7.00:1）
- --au-color-text-disabled #BFBFBF（规范定义于组件1/2.txt；WCAG 1.4.3 豁免）
- --au-color-border-strong #F0F0F0（规范未定义、实现补齐）
- 同步 legacy 别名；修复 colors_and_type.css 一处重复注释起始行

修复
- Countdown 首帧空白：setInterval(render, 1000) 首次执行要等 1 秒，
  期间容器为空。改为定义函数后立即执行一次再挂 interval

验证（本轮核心验收）
- 逐组件验证「改令牌 → 元素是否跟着变」：79/79 全部响应
- 过程中修正两处测量方法缺陷（初测 40/79 是误报）：
  ① 选择器 .demo * 在无 .demo 容器的页面抓不到元素
  ② 探针令牌选错 —— Breadcrumb 用 text-tertiary 而只改了 text-body
- CSS 结构完整：158 个文件括号平衡、var(--*) 引用全部有定义
- 回归保持 100%：961 断言 / 0 失败 / 79 页全通过，三次连跑一致

2026-09-11 17:29:30 +08:00

18 KiB

Raw Blame History

Aurora Admin 现状问题分析与改造清单

修复进度（2026-09-10 v1.3.0）：v1.1.1 完成 A1 搜索增强、A2 For Agents + llms.txt、A3 站内 Changelog + 版本同步、B2 暗色令牌映射、B4 主题预设库；v1.2.0 完成 B1 契约第一批（21/79）、B3 Playground、C1 交叉引用、C3 headless 回归骨架、C4 静态薄壳 + sitemap。

v1.4.0（本次）：组件层全面令牌化 —— 修复「93.4% 颜色硬编码、改令牌组件不变」的根基问题。两层共替换 1202 处（组件样式表 915 + 演示页内嵌样式 287），令牌 71→74；浏览器逐组件验证 79/79 可换肤；顺带修复 Countdown 首帧空白。

v1.3.3：中英双语落地（site/i18n.js 330 条字典 + 顶栏切换 + 偏好持久化），覆盖全部页面；回归时序根治（DensitySwitcher 偶发失败 → 就绪轮询，四次连跑 100%）。

v1.3.2：契约第三批 43 份落地，79/79 全量契约化；新增令牌导出三格式（CSS / W3C DTCG / Figma Tokens）；规格原文色彩系统同步至 AA 达标值。

前序：v1.3.0 修复验收链路（测试页原以静态快照断言、剥离 script 后 DOM 为空，75.1% 属结构性误报 → 改 iframe 真实渲染 + 跨帧断言）；v1.3.1 完成无障碍与令牌合规，回归达 100%（961 断言 / 0 失败 / 79 页全通过）。

依据：《竞品网站检查报告.md》（2026-09-08）+ 对当前代码的逐文件核实（site/app.js 1671 行、site/style.css、components/index.json、data.json、tests/）性质：问题分析 + 可执行改造清单。本文只做分析与方案，未改动任何文件。版本基准：data.json meta v1.0.0（79 组件 = 10 核心 + 69 扩展），CHANGELOG v1.1.0，6 大分类（通用 4 / 导航 10 / 录入 24 / 展示 20 / 反馈 15 / 系统 6）

〇、先修正竞品报告中的三处误判（代码核实后）

竞品报告基于 PLAN.md 的描述做对比，逐文件核实后有三处需要修正——当前代码比报告假设的更强，后续改造重点也因此不同：

报告原判断	代码核实结果	修正后的问题定性
❌ 暗色模式缺失（v1.2 计划）	✅ 已实现：`index.html` 深浅切换 FAB + `app.js:1534-1545` `aa-mode` 持久化 + `style.css:973-991` `html.aa-dark` 令牌覆盖	不是"有没有"，而是覆盖不完整（见问题 2）
❌ 每组件 API 表未上网	✅ 已实现：`app.js:637 extractComponentAPI()` 从 frameworks 源码自动提炼，详情页渲染 Props / Events / Slots 三表（`app.js:805 buildApiSection`）	不是"有没有"，而是69 个扩展组件无契约保障、提炼靠启发式扫描（见问题 1）
❌ 测试体系未在站点露出	✅ 首页 Hero 已有「测试总览」按钮（`app.js:213`），`tests/index.html` 存在（82 个文件）	问题只剩无 headless 回归 + 断言未接入 CI（见问题 8）

一、当前问题清单（按严重度）

P0 — 影响专业度与可信度

问题 1：承诺了但没实现的搜索增强（文档与实现不符）

PLAN.md §4.2 与 §7 验收标准声称 v1.1 已含「分类过滤 chip、关键词 <mark> 高亮、模糊容错」；CHANGELOG.md v1.1.0 同口径。
实际 app.js:1581 doSearch() 只有 zh/en/slug 三字段 indexOf 子串匹配，无分类 chip 行、无高亮包裹、无模糊容错（拼音/编辑距离）。
风险：审计视角下这是"验收标准声称 ✅ 但代码没有"——对一个以「可被审计」为卖点的文档体系是硬伤。竞品全部有即时搜索体验（Element Plus / Ant Design 均含分类过滤与高亮）。

问题 2：暗色模式是半成品

style.css 仅有 5 条 html.aa-dark 规则（974-991 行：页面背景、topbar、demo-stage、demo-code）；.design_library/aurora-admin/components.css 暗色规则 0 条；colors_and_type.css 未提供暗色令牌组。
深色模式下只有站点骨架变色，正文卡片、表格、侧栏、搜索弹窗等大量表面仍按浅色令牌渲染；演示 iframe 保持浅色是有意设计（style.css:990 注释），但这一策略没有写进设计规范页，使用者会误以为未完成。
竞品对照：7 家中 6 家有完整暗色（Ant Design 甚至有整套暗色主题预设）。

问题 3：契约覆盖 79/79（已闭环）

components/ 目录现有 79 份契约 JSON（v1.3.2 补齐第三批 43 份），79 个组件全部契约化，不再依赖 extractComponentAPI() 的源码正则启发式。
已消除的风险：此前跨 4 端命名差异（H5 class、React camelCase、Vue kebab-case）导致的漏提/错提，现由契约为准、源码扫描兜底。

问题 4：AI 消费入口未公开（竞品已全员押注的方向）

本地 .design_library/aurora-admin/SKILL.md、metadata.json、library-consumption.json 已具备 Agent 就绪底座，但文档站没有 For Agents 页、没有 llms.txt、无 MCP 描述文件。
竞品对照：Ant Design 有 docs/react/for-agents-cn.md + 官方 CLI/MCP；Semi 首页横幅「MCP & Skills」；TDesign 2025-08 已上线 MCP 工具。这是 2026 年设计系统的标配入口，而 Aurora 的实现成本极低。

问题 5：维护信号不上网

CHANGELOG.md 只是仓库文件，文档站内无更新日志页、组件条目无版本徽章；首页 Hero 版本号停在 data.json 的 v1.0.0（实际已 v1.1.0，两处不同步——build-site.ps1 未从 CHANGELOG 取版本）。
竞品对照：Element Plus / Ant Design / Naive UI 每个组件标注引入版本；DevUI 的教训是"更新停滞感"本身就是负资产。

P1 — 高价值补齐

问题 6：无 Playground（在线编辑/试玩）

详情页 demo 是只读 iframe（buildDemoCard），代码可展开不可改。竞品标配：Element Plus.run、Semi Live Code、Arco CodeSandbox。
Aurora 的组件是零依赖纯 HTML，反而是 7 家竞品中最容易做 Playground 的（iframe srcdoc 即可，无需打包器）。

问题 7：主题定制器缺预设与令牌分组

theme-panel 仅 4 个颜色键 + 复制覆盖代码；无预设主题一键切换（Ant Design 13 套 / Semi DSM 主题商店 / Naive UI 换主题演示）。
令牌文件里 au-* 令牌是分组注释的（品牌/中性/语义），面板未按组呈现，也没有「只改语义色不改品牌色」的分层能力。

问题 8：测试断言未接入自动回归（v1.3.0 已修链路，剩余为真实缺口）

tests/*.html 已带 data-assert / data-status 机器可读标记，tools/run-regression.mjs 与 tests/_collect.html 两种 runner 均可批量执行并产出 tests/report.json。
v1.3.0 修正：此前测试页把演示页 body 抽成静态快照（剥离 <script>）且未引入组件 CSS，而演示页 DOM 全靠内联脚本渲染，导致断言在空 DOM 上大面积失败——原 75.1% 不是真实质量数据。现改为 iframe 直载真实演示页 + 跨帧断言，基线 960 断言 / 85.1%（N/A 27）。
剩余失败项是演示页的真实缺口：状态覆盖 45、对比度 35、ARIA 33、键盘可达 15、硬编码 hex 9、变体 2。
Semi 宣称"单测+E2E+视觉对比 90% 覆盖"并作为首页卖点；Aurora 现已有可复现证据链，但覆盖率仍待补齐。

P2 — 增强项

问题 9：无组件交叉引用 — 无「相似组件 / 搭配使用 / 推荐·慎用」（TDesign Button 页特色栏目）。契约 JSON 已有「不发明 / 未明示 / 使用要点」字段，具备映射条件。 问题 10：i18n 双语（v1.3.3 已闭环） — site/i18n.js 330 条字典，中文源串作键（未收录自动回退），顶栏 中/EN 切换 + aa-lang 持久化，覆盖 9 个路由与全部组件详情页。 问题 11：无设计资源下载 — css.json 已是结构化令牌，但没有导出 Figma Tokens / 设计资源包入口（竞品标配 Figma/Sketch 资源）。 问题 12：可爬取性弱 — hash 路由 SPA 全靠 JS 渲染；data.json 已生成（2026-09-07）但无 sitemap、无每组件静态入口，搜索引擎与 LLM 爬虫拿不到组件页内容。 问题 13：组件页无 FAQ（Ant Design 每组件 FAQ 模式，高频问题沉淀）。

二、可改造项目清单（11 张项目卡）

工作量：S ≤ 1 天，M = 2-4 天，L ≥ 1 周（单人）。均不改 site/dev-server.js 主流程、不动 frameworks 源码，遵守 PLAN §8 约束。

A1 · 搜索增强「补票」（P0，S）

做法：doSearch() 结果行加分类 chip 过滤行 + 命中字段 <mark> 包裹 + 匹配不到时回退单字拆分匹配（中文模糊容错的最小实现）。
落点：site/app.js doSearch/bindSearch + site/style.css 搜索弹窗样式。
对标：Element Plus Ctrl+K、Ant Design 搜索。
理由：把"声称已做"变成"真的做了"，消除审计硬伤，成本半天。

A2 · For Agents 页 + llms.txt（P0，S）

做法：新增 #/agents 页（渲染 SKILL.md 内容：令牌约定、契约 schema、5 端文件命名规则、消费方式），站点根放 llms.txt 指向 data.json / components/index.json / 各契约 JSON；可选附 MCP tool 描述 JSON。
落点：site/app.js 新 render 函数 + site/llms.txt。
对标：Ant Design For Agents、TDesign MCP、Semi MCP & Skills。
理由：Aurora 的 JSON 化令牌 + 契约 + data.json 天然适合 Agent 消费，这是性价比最高的差异化项目。

A3 · 站内更新日志页 + 组件版本徽章（P0，S/M）

做法：CHANGELOG.md 构建时解析进 data.js，新增 #/changelog 页；组件条目按 specBatch + 契约登记版本渲染小徽章（如 1.1.0）；build-site.ps1 从 CHANGELOG 提取当前版本写入 data.js meta，消除 v1.0.0/v1.1.0 不同步。
落点：build-site.ps1、site/app.js renderChangelog、总览/详情页徽章样式。
对标：Element Plus 版本徽章、Ant Design 更新日志页。

B1 · 扩展组件契约补齐 69 个（P0，L，分批）

做法：按使用频次分三批补契约 JSON（第一批：输入类高频 15 个——表单场景是 B 端核心；第二批：展示类 15 个；第三批：其余）。每份契约补全 variants/props/events/a11y/使用要点/不发明/未明示字段；extractComponentAPI() 改为契约优先、源码扫描兜底，两者 diff 时以契约为准并在页面标注「契约化 ✓」（现有 app.js:985 契约 chip 已有此交互）。
落点：.design_library/aurora-admin/components/<slug>.json（新增 69 个）+ build-site.ps1 注入 data.js。
对标：Ant Design 组件级 Design Token 双层表、Semi 类型化 API。
理由：这是「可被审计」从口号变事实的关键工程，也是 B1/A1/A3 之外所有内容模块的数据地基。

B2 · 暗色模式令牌映射补全（P1，M）

做法：colors_and_type.css 增加 html.aa-dark 下的语义令牌映射组（页面/卡片/边框/四级文字/五种语义色的暗色值），components.css 改用令牌引用后自动生效；「演示 iframe 保持浅色」策略作为显式规则写进设计规范页与组件页说明。
落点：colors_and_type.css、components.css（仅令牌引用方式，不改组件视觉）、app.js renderDesign 增补说明。
对标：Ant Design 暗色算法、Naive UI 内置深色。

B3 · Playground（P1，M）

做法：demo 卡片加「在线编辑」模式——代码区变 textarea，iframe 用 srcdoc 实时重渲染，提供「复位 / 复制 / 全屏」；零依赖，不引入任何编辑器库（textarea + 等宽字体即可起步）。
落点：site/app.js buildDemoCard/buildCodeArea 扩展。
对标：Semi Live Code、Element Plus Playground。
理由：5 端纯 HTML 源码使 Aurora 成为最容易实现真·Playground 的竞品，反而可以后发先至。

B4 · 主题预设库（P1，S/M）

做法：theme-panel 增加 6 套预设（科技蓝/暗夜/暖橙/极简灰/高对比无障碍/森林绿），点击即整组覆盖 au-* 令牌并持久化到现有 aa-theme 机制；预设数据外置为 JSON，可继续扩充。
落点：site/app.js theme-panel、site/presets.json（新增）。
对标：Ant Design 13 套主题预设、Semi DSM 主题商店（Aurora 的"主题商店"雏形）。

C1 · 组件交叉引用（P2，S）

做法：详情页底部渲染「相似组件 / 常与 XX 搭配 / 推荐·慎用」卡，数据来源：同分类组件 + 契约 JSON 的使用要点/不发明字段（规则生成，无需人工全量维护）。
落点：site/app.js renderComponent 尾部 + 契约 schema 扩展字段。
对标：TDesign「相似组件」「组件搭配使用」「推荐/慎用示例」。

C2 · i18n 英文版（P2，M）

做法：CAT_LABELS/导航/首页文案字典化为 site/i18n.js（zh/en），顶栏加语言切换并持久化；组件名本身双语已具备（splitName）。
对标：全部 7 家竞品均有中英双语。

C3 · headless 回归（P2，M）— v1.3.0 已完成

做法：用 Playwright 批量加载 tests/*.html，读取 data-assert/data-status 汇总通过率，输出 JUnit XML；文档站首页展示最近一次回归结果。
落地：tools/run-regression.mjs（Playwright + JUnit XML）+ tests/_collect.html（零依赖浏览器收集器，同口径）；首页 Hero 读 tests/report.json 显示通过率。
关键修正：测试页原先把演示页 body 抽成静态 DOM，剥离 <script> 后内容为空（演示页 DOM 全靠内联脚本渲染）且缺组件 CSS —— 断言在空 DOM 上跑出的 75.1% 是结构性误报。v1.3.0 改为 iframe 直载真实演示页 + 跨帧断言，基线 960 断言 / 85.1%。
落点：run_tests.py 扩展或新增 run_e2e.py。
对标：Semi「三种测试 + 90% 覆盖率」的公开证据链。

C4 · 令牌资源下载 + 静态化 SEO（P2，M）

做法：①设计规范页加「下载令牌包」：css.json → Figma Tokens JSON / W3C Design Tokens 格式 / CSS 变量文件三选一；②build-site.ps1 为 79 个组件生成静态 site/components/<slug>.html 薄壳（SEO 可爬）+ sitemap.xml。
对标：竞品 Figma/Sketch 资源标配；静态化解决 SPA 可爬取性。

三、内容模块盘点与新增建议

现有 10 模块状态（PLAN §2 修订版）

#	模块	状态	备注
1	品牌与原则	✅	README + 首页 Hero
2	设计令牌	✅	设计规范页 + css.json，缺暗色组与导出
3	组件契约	✅ 79/79	全量契约化（核心 6 + 输入类 15 + 展示类 15 + 第三批 43）
4	批次映射	✅	index.json schemaVersion 3
5	全量预览	✅	总览 iframe + 分类/关键词过滤
6	首页/总览/快速开始/设计规范	✅	四页 + 详情页
7	全局搜索	⚠️	基础可用，增强未落地（问题 1）
8	主题定制器	⚠️	有，缺预设（问题 7）
9	每组件测试页	✅	79 页 + index + 批量收集器；iframe 真实渲染，基线 85.1%（问题 8）
10	Changelog/Roadmap	⚠️	仓库文件，未上网（问题 5）

建议新增 6 个内容模块

#	新模块	落点	支撑项目
11	For Agents / AI 消费入口（含 llms.txt、契约 schema 说明）	`#/agents` 页 + `site/llms.txt`	A2
12	Playground 在线试玩	组件详情页内嵌	B3
13	站内更新日志 + 组件版本徽章	`#/changelog` 页 + 组件条目	A3
14	主题预设库（主题商店雏形）	theme-panel + presets.json	B4
15	资源下载中心（令牌包三格式导出）	设计规范页内嵌	C4
16	组件交叉引用（相似/搭配/慎用）+ FAQ	详情页内嵌	C1、问题 13

四、改造路线图（映射版本）

版本	内容	项目	直接效果
v1.1.1（1-2 天，hotfix 性质）	搜索增强补票 / For Agents + llms.txt / 站内 Changelog + 版本同步	A1、A2、A3(S)	消除"声称≠实现"审计硬伤；补上 2026 年竞品标配的 AI 入口与维护信号
v1.2.0（1-2 周）	契约分批补齐（第一批 15 个）/ 暗色令牌映射 / Playground / 主题预设	B1(批1)、B2、B3、B4	API 可信度、暗色完整性、可试玩、可换肤四项对齐竞品一线水平
v1.3.0（本次）	验收链路修复（iframe 真实渲染 + 跨帧断言）/ 基座焦点环 / 契约第二批 15 个（展示类）	C3 修正、B1(批2)	回归数字从误报变可信（85.1% / 960 断言）；契约 36/79；焦点环一次性修 66 页
v1.3.2（本次）	契约第三批 43 份（全量 79/79）/ 令牌导出三格式 / 规格色彩同步	B1(批3)、C4	「可被审计」从口号变事实；令牌可被设计工具与其它工程直接消费
v1.4.0（后续）	i18n 双语、组件 FAQ、契约 usageHints 驱动的交叉引用增强	C2、问题 13	形成完整证据链与双语能力，可对外交付

判断依据（一句话版）

先补票再做新功能：搜索增强是 PLAN/CHANGELOG 声称已交付的，最优先修复。
AI 入口是 2026 年的"国际化"：所有竞品已就位，Aurora 底座现成，半天工作量换一个差异化标签。
契约是所有内容模块的地基：交叉引用、版本徽章、Agent 消费、API 可信度全部依赖它，值得投入最大块时间。
Aurora 的零依赖纯 HTML 是劣势也是王牌：竞品的 Playground 需要打包器，Aurora 用 iframe srcdoc 就能做，B3 的完成度有机会反超。

五、显式不做（本轮）

不引入 npm 依赖 / 不接 Storybook（保持零依赖，PLAN §8 原则）
不改 frameworks/ 源码与 5 端实现
不重构 app.js 主体（新功能全部走新增函数/新增数据文件）
不做 Figma 源文件（无设计源文件，用令牌导出代替）

18 KiB Raw Blame History Unescape Escape