aurora-admin/ROADMAP.md

Aurora Admin · 长期路线图与任务包

文档性质：交给执行模型的工程规划。每个任务包自带验收命令与失败判据，拿到即可开工，不需要再问。 基线版本：v1.4.1（2026-09-11） 规划人：海鸥（规划师角色） 更新约定：任务完成时在本文件对应任务包下追加 ✅ 完成于 <commit>，不要删原计划。

---

〇 · 交接约定（执行模型必读）

1. 零依赖约束不可破：不引入 npm 运行时依赖。构建/测试脚本用 Node 内置能力或 PowerShell。
2. build-site.ps1 必须 ASCII-only：PS5.1 按 ANSI 读无 BOM 文件，脚本里出现非 ASCII 字面量会被损坏。中文文案放 UTF-8 模板。
3. 改结构要改模板：tests/<slug>.html 是生成物，改它没用 —— 改 tests/_template.html 后重跑 run-tests.ps1。
4. 改样式要改内嵌层：演示页的内嵌 <style> 才是实际生效的样式（见 v1.4.0 教训）。只改 frameworks/*.css 可能不生效。
5. 验收以实测为准：跑本文件给出的命令，把输出贴进交付说明。不要写"已完成"而不给证据。
6. 单次改动后必须跑回归：tests/_collect.html 八次连跑，100% / 0 失败 / 0 超时 才算过。

---

一 · 现状基线（全部为实测数据）

1.1 资产规模

项	数量	测量方式
组件	79	components/index.json
5 端实现文件	395	ls frameworks/*.{html,css,jsx,vue2.vue,vue3.vue} 各 79
契约 JSON	79（全量）	ls .design_library/aurora-admin/components/*.json
契约 usageHints	358 条	遍历契约累加
契约 unknowns	139 条	同上（现成的 FAQ 素材）
契约 doNotInvent	101 条	同上
设计令牌	75 个	site/data.json → tokens.length
i18n 字典	330 条	site/i18n.js
测试断言	961 条（12.2/页）	tests/report.json
文档站路由	9 个	home/overview/guide/design/changelog/agents/component/scenario/tests

1.2 质量指标

项	值	说明
回归通过率	100%	八次连跑一致，0 失败 0 超时
N/A 断言	36（3.7%）	静态组件无交互面、单实例组件无多变体，已逐条核实
契约保真度	93.9% 逐字命中规格	余 22 条为同义改写，非发明
令牌语义错配	0 / 1313 处	属性与令牌角色全部匹配
i18n 质量	0 残留中文、0 未翻译	326 条字典
组件可换肤	79/79	逐组件改令牌比对样式签名

1.3 性能基线

指标	值	说明
文档站传输量	1247 KB	7 个资源
其中 data.js	1058 KB（85%）	← 最大优化目标
app.js	101 KB	未压缩
style.css	40 KB	未压缩
DOMContentLoaded	345 ms	本地 dev-server，线上更慢
每详情页额外	iframe 1 个	加载对应演示页

1.4 实测缺口（按严重度）

#	缺口	实测证据	影响
G1	无 LICENSE	ls LICENSE → 不存在	法律上不可用，对外交付的硬阻塞
G2	无分发机制	无 package.json / 无 CDN / 无发布流程	用户拿不到，只能 clone 仓库
G3	CI 无测试	.github/workflows/ 只有 deploy-pages.yml	回归靠手动，质量无持续保障
G4	暗色模式是假的	令牌层 aa-dark 规则 0 条、组件层 0 条、仅站点骨架 7 条	CHANGELOG 曾称"补全"，实为第 6 次声称≠实现
G5	跨端一致性无验证	5 端 395 文件，无任何自动比对	H5/React/Vue2/Vue3 视觉是否一致无从知晓
G6	data.js 1MB	占传输量 85%	首屏慢，移动端更差
G7	RTL 未支持	逻辑属性 0 处 / 物理属性 22 文件	阿拉伯语等市场不可用
G8	断言偏结构	12 项/页，多为"元素存在"，无"点击后发生什么"	行为回归无覆盖

---

二 · 长期愿景与阶段划分

2.1 目标状态（12 个月）

一句话：从「一个做得很完整的组件库仓库」，变成「一个能被外部团队直接采用的设计系统产品」。

拆成四个可验证的终态：

1. 可交付 —— 有许可证、有分发渠道、有 CI 保障，外部团队 5 分钟内能用上。
2. 可信 —— 关键声称（暗色、跨端一致、无障碍）全部有自动化证据，不靠文档承诺。
3. 完整 —— 覆盖国际化（含 RTL）、无障碍实测、性能预算。
4. 生态 —— 设计工具链打通（Figma）、典型页面可直接复用、有版本发布节奏。

2.2 阶段划分与决策依据

阶段	主题	解决	决策依据
S1	可交付	G1 G2 G3 G6	前三个是对外交付的硬阻塞：没许可证不能商用，没分发拿不到，没 CI 质量会退化。G6 顺手做（data.js 占 85% 传输量，收益最大）
S2	可信	G4 G5 G8	都是「声称了但没证据」。G4 是第 6 次声称≠实现，必须先止血
S3	完整	G7 + 无障碍实测	RTL 与无障碍是竞品 7 家里的分水岭（3 家有 RTL）
S4	生态	Figma/模板/发布	前两阶段完成后，生态建设才有意义

为什么这个顺序：S1 是"能不能用"，S2 是"能不能信"，S3 是"够不够全"，S4 是"好不好用"。顺序颠倒会做出没人敢用的产品。

---

三 · 任务包

格式：目标 → 依据 → 依赖 → 路径 → 步骤 → 验收 → 失败判据 每个任务包独立可执行，除标注依赖外互不阻塞。

---

S1-P1 · LICENSE 许可证 ｜ 预算 ~10 min ｜ 优先级 P0

目标：仓库根目录存在 LICENSE，明确授权范围，移除对外交付的法律阻塞。

依据：G1。CONTRIBUTING.md 与 README.md 都在讲如何贡献与使用，但没有许可证意味着默认保留所有权利，外部团队法务不会放行。

依赖：无。需用户确认许可证类型（见下方决策点）。

路径：LICENSE（新建）

步骤：

1. 确认许可证类型。若用户未指定，默认 MIT（与本项目"零依赖、鼓励复用"的定位一致），并在交付说明里标注"如需变更请告知"。
2. 写入标准 MIT 全文，版权行为 Copyright (c) 2026 Aurora Admin。
3. 在 README.md 增加 ## 许可证 段，链接到 LICENSE。
4. 在 CHANGELOG.md 的 [Unreleased] 下追加 ### Added — LICENSE。

验收：

# 文件存在且包含关键条款
test -f LICENSE && grep -q "MIT License" LICENSE && grep -q "WITHOUT WARRANTY" LICENSE && echo "LICENSE OK"

# README 有链接
grep -q "LICENSE" README.md && echo "README OK"

预期输出：

LICENSE OK
README OK

失败判据：任一条命令无输出，或 LICENSE 里出现非标准条款（自行增删免责声明）。

决策点（需用户输入）：许可证类型。MIT 是默认推荐；若项目未来要商业化或要求衍生作品开源，应改 Apache-2.0 或 MPL-2.0。

✅ 完成（MIT，采用默认选择） — 验收输出：

LICENSE OK
README OK

同步改动：LICENSE（MIT 全文）、README.md（新增「许可证」段 + 版本号更新为 v1.4.1 + 指向本路线图）。 如需改为 Apache-2.0 / MPL-2.0：替换 LICENSE 全文，同步 README.md 与未来 package.json 的 license 字段即可，无其他联动。

---

S1-P2 · npm 分发 ｜ 预算 ~2 h ｜ 优先级 P0

目标：npm install aurora-admin-design 能拿到令牌 + 组件样式；<link> 可直接引 CDN。

依据：G2。当前用户只能 clone 整个仓库（5.1MB git + 2.6MB site），对"只想用几个组件"的人成本过高。

依赖：S1-P1（package.json 需声明 license 字段）。

路径：

• package.json（新建）
• .npmignore（新建）
• tools/build-dist.mjs（新建，产出分发产物）
• dist/（构建产物，加入 .gitignore）

步骤：

1. 建 package.json，关键字段：

   {
     "name": "aurora-admin-design",
     "version": "1.4.1",
     "description": "B 端中后台设计系统 · 79 组件 × 5 端 · 零运行时依赖",
     "license": "MIT",
     "main": "dist/tokens/tokens.css",
     "files": ["dist/", "README.md", "LICENSE"],
     "scripts": {
       "build": "node tools/build-dist.mjs",
       "test": "node tools/verify-dist.mjs"
     },
     "keywords": ["design-system", "admin", "css-variables", "design-tokens"],
     "sideEffects": ["*.css"]
   }
   

   注意：不声明任何 dependencies —— 这是硬约束。
2. 写 tools/build-dist.mjs（Node ESM，零依赖），产出：
   • dist/tokens/tokens.css、tokens.json（复用 build-site.ps1 的产出）
   • dist/components/<slug>.css × 79 + dist/components/index.css（聚合）
   • dist/components/<slug>.html × 79（静态演示）
   • dist/README.md（用法速查，从主 README 节选）
   • dist/manifest.json（组件清单 + 版本 + 文件校验和）
3. 写 .npmignore 排除 site/、tests/、frameworks/*.jsx|vue*、.github/、*.png。
4. 在 README.md 增加「安装」段，给出 npm / CDN / 直接下载三种方式。

验收：

# 1) 构建产物齐全
node tools/build-dist.mjs
test -f dist/tokens/tokens.css && echo "tokens OK"
test -f dist/components/index.css && echo "aggregate OK"
test $(ls dist/components/*.css | wc -l) -ge 80 && echo "79 components + index OK"

# 2) 无运行时依赖（硬约束）
node -e "const p=require('./package.json'); if(p.dependencies) { console.error('FAIL: 不允许 dependencies'); process.exit(1) } console.log('zero-dep OK')"

# 3) 分发内容不含开发资产
npm pack --dry-run 2>&1 | grep -q "site/" && echo "FAIL: 打包含 site/" || echo "pack contents OK"

# 4) 产物可用（起本地服务，浏览器打开验证）
node -e "const fs=require('fs');const c=fs.readFileSync('dist/components/index.css','utf8');if(!c.includes('--au-color-brand'))process.exit(1);console.log('css usable OK')"

预期输出：

tokens OK
aggregate OK
79 components + index OK
zero-dep OK
pack contents OK
css usable OK

失败判据：

• package.json 出现任何 dependencies
• npm pack --dry-run 输出含 site/ 或 tests/
• dist/components/*.css 少于 80 个

已知风险：npm pack 需要网络（首次可能要求登录）。若无网络，跳过第 3 条验收并在交付说明注明。

---

S1-P3 · CI 回归流水线 ｜ 预算 ~1.5 h ｜ 优先级 P0

目标：每次 push/PR 自动跑回归，失败则阻止合并；结果可在 GitHub Actions 页面看到。

依据：G3。当前只有部署 workflow，回归靠人工手动跑 _collect.html，质量随提交退化不可见。

依赖：无（可与 P1/P2 并行）。

路径：

• .github/workflows/regression.yml（新建）
• tools/run-regression.mjs（已存在，需改造为无网可用）

步骤：

1. 现状：tools/run-regression.mjs 依赖 playwright（npm 包），与"零依赖"约束冲突。 解法：CI 里允许用 npx playwright（CI 环境的临时工具，不进 package.json 的 dependencies），或用 devDependencies + 在文档说明"CI 专用，运行时不依赖"。 推荐：把 playwright 放进 devDependencies（这是构建期工具，不违反"零运行时依赖"）。
2. 写 workflow：

   name: Regression
   on: [push, pull_request]
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with: { node-version: '20' }
         - run: npm i -D playwright && npx playwright install --with-deps chromium
         - run: node site/dev-server.js &
         - run: sleep 3
         - run: node tools/run-regression.mjs
         - uses: actions/upload-artifact@v4
           if: always()
           with: { name: regression-report, path: tests/report*.json }
   

3. run-regression.mjs 需改造：目前是纯 Node 脚本，要确保它在 Linux 下也能找到报告输出路径（Windows 路径分隔符问题）。
4. 增加失败阈值：passRate < 100 时 process.exit(1)。

验收：

# 本地模拟 CI 步骤
node site/dev-server.js & sleep 3
node tools/run-regression.mjs
echo "exit=$?"
# 期望 exit=0 且 passRate=100

推送后在 GitHub Actions 页面确认 workflow 跑绿（需用户操作）。

预期输出：

passRate 100% | pages 79 (all-pass 79) | assertions 925/925
written: tests/report.json, tests/report-junit.xml
exit=0

失败判据：

• workflow 文件语法错误（用 actionlint 或 GitHub 页面报错验证）
• 本地模拟跑出 exit != 0
• passRate < 100 时没有 exit 1

已知风险：playwright install 在 CI 上约需 1-2 分钟，可通过缓存加速（后续优化项）。

---

S1-P4 · data.js 瘦身 ｜ 预算 ~3 h ｜ 优先级 P0

目标：site/data.js 从 991 KB 降到 < 150 KB（实测可达成 ~110 KB）。

依据：G6。实测 data.js = 1058 KB（传输量），占文档站总传输 85%。

已完成的诊断（无需重做）：

data.json 体积构成（实测）
  总计: 991KB
  components   974KB  98.3%   ← 唯一大头
  changelog     12KB   1.2%
  tokens         5KB   0.5%

components[] 内部（单组件）
  .sources     15.7KB  ← 5 端源码全文
  .contract     0.8KB
  .specLines    0.2KB
  .files        0.2KB
  其余          <0.1KB

全部组件 .sources 合计: 888KB（占 data.json 的 89.6%）

结论：sources 字段（5 端源码全文，仅供详情页代码区展示）占了 89.6%。把它移出 data.js 改为按需 fetch，data.js 降到 ~110 KB（−89%）。

依赖：无。

路径：

• build-site.ps1（改造产出：分文件写源码）
• site/app.js（改造消费：按需 fetch + loading 态）
• site/sources/<slug>/<kind>.txt（新增产出目录，79 × 5 = 395 个文件）
• site/data.js / site/data.json（产出物，不手改）

步骤：

1. 改造 build-site.ps1：
   • 新增：把每个组件的 5 端源码写到 site/sources/<slug>/<kind>.txt（kind ∈ html/css/jsx/vue2/vue3）
   • 修改：data.js 里 components[].sources 改为 sourcesRef: "sources/<slug>/"（只留路径，不留内容）
   • 保持 data.json 完整（For Agents 页承诺"一次请求拿到全部"，不能破坏 —— 这是硬约束）
2. 改造 app.js：
   • 详情页渲染代码区时 fetch('sources/<slug>/<kind>.txt')
   • 加 loading 态（复用现有 .demo-code 样式）
   • 加失败兜底（fetch 失败显示"源码加载失败"+ 重试按钮，不留空白）
3. 验证 For Agents 承诺未破：data.json 仍然包含完整 sources。

验收：

# 1) 体积达标（实测应约 110KB）
node -e "
const fs=require('fs');
const core=fs.statSync('site/data.js').size;
console.log('data.js:', (core/1024).toFixed(0)+'KB');
if(core/1024 > 150) { console.error('FAIL: 超过 150KB 预算'); process.exit(1) }
console.log('budget OK');
"

# 2) 源码文件已分离（395 个）
n=$(ls site/sources/*/*.txt 2>/dev/null | wc -l)
echo "sources files: $n"
test "$n" -eq 395 && echo "split OK"

# 3) data.json 未缩水（For Agents 承诺不变 —— 硬约束）
node -e "
const d=require('./site/data.json');
const c=d.components.find(x=>x.slug==='button');
if(!c.sources||Object.keys(c.sources).length!==5) { console.error('FAIL: data.json 的 sources 被破坏'); process.exit(1) }
console.log('data.json intact OK');
"

# 4) data.js 里已无源码正文
node -e "
const d=require('./site/data.js')||{};
" 2>/dev/null || node -e "
const fs=require('fs');
const s=fs.readFileSync('site/data.js','utf8');
// 源码正文特征：不应再出现完整 HTML 文档
if(s.includes('<!DOCTYPE html>')) { console.error('FAIL: data.js 仍含源码正文'); process.exit(1) }
console.log('sources removed OK');
"

浏览器实测：

• 打开 #/component/button，代码演示区正常显示
• Network 面板出现 sources/button/html.txt 请求
• 断网/404 情况下显示兜底提示而非空白

预期输出：

data.js: ~110KB
budget OK
sources files: 395
split OK
data.json intact OK
sources removed OK

失败判据：

• data.js > 150 KB
• site/sources/ 文件数 ≠ 395
• data.json 的 sources 字段被动过（会破坏 For Agents 承诺）
• 详情页代码区空白或报错

为什么不直接压缩：gzip 能压到 ~200KB，但解析时间与内存占用仍在（1MB JSON 在低端机解析约 100-200ms）。且 Pages 默认已开 gzip，压缩不是增量收益。根治要减体积。

---

S1-P4b · 首屏资源优化 ｜ 预算 ~2 h ｜ 优先级 P1

目标：文档站首屏传输从 1247 KB 降到 < 300 KB。

依据：P4 完成后 data.js ~110KB，但 app.js 101KB + style.css 40KB 仍是未压缩文本。

依赖：S1-P4。

步骤：

1. app.js（101KB 单文件）按路由拆分：首页逻辑与详情页逻辑分离，详情页按需加载。
2. 关键 CSS 内联（首屏可见部分），其余异步加载。
3. 加入 build-site.ps1 的产出：.min.js / .min.css（用 Node 内置能力做简单压缩：去注释、去多余空白）。

验收：

node -e "
const fs=require('fs');
const files=['site/data.js','site/app.js','site/style.css','site/i18n.js','.design_library/aurora-admin/colors_and_type.css'];
const total=files.reduce((s,f)=>s+fs.statSync(f).size,0);
console.log('首屏资源合计:', (total/1024).toFixed(0)+'KB');
if(total/1024>300){console.error('FAIL: 超过 300KB');process.exit(1)}
console.log('payload OK');
"

---

S2-P5 · 暗色模式真正实现 ｜ 预算 ~1 天 ｜ 优先级 P0

目标：html.aa-dark 下，79 个组件的演示页全部正常反色，对比度仍满足 WCAG AA。

依据：G4。实测令牌层 aa-dark 规则 0 条、组件层 0 条，只有站点骨架 7 条。CHANGELOG.md 的 v1.1.1 条目称"暗色模式令牌映射补全"—— 这是第 6 次声称≠实现。

依赖：S1-P4（体积优化后改 app.js 更清爽，非硬依赖）。

路径：

• .design_library/aurora-admin/colors_and_type.css（加暗色令牌组）
• site/style.css（清理原有的 7 条临时规则）
• frameworks/*.html 的内嵌样式（若需微调）
• tests/_runtime.js（增加暗色断言）

步骤：

1. 设计暗色令牌组（在 colors_and_type.css 里加 html.aa-dark 块）：
   • 背景层：page-bg #14161C → card-bg #1C1F26 → table-header-bg #22262E（三层递进）
   • 文字层：text-title #E8EAED → text-body #C9CDD4 → text-secondary #9CA3AF → text-placeholder #6B7280
   • 边框：border #2A2F38、border-strong #363B45
   • 品牌色：向白提亮（#2F54EB 在深底上对比度不足），推荐 #5B7CF5 系列
   • 语义色：同样提亮（#2E7D0A → #4CAF50 一类）
2. 每个色值都要算对比度，写脚本验证（复用 v1.3.1 的方法）：

   node -e "
   // 对每个暗色令牌算 WCAG 对比度，全部 ≥4.5:1（文字）或 ≥3:1（图标）
   "
   

3. 演示页反色策略：v1.4.0 的注释说"演示 iframe 保持浅色，避免样例反色失真"。这条策略要么：
   • A：改成可配置 —— 站点暗色时演示页也反色（更真实，但要确保反色后不难看）
   • B：保持浅色，但在设计规范页显式说明这是有意设计 推荐 A，因为用户开暗色就是想整体变暗，局部刺眼是体验倒退。若选 A，需给演示页传 ?theme=dark 或用 postMessage 通知。
4. 加断言：_runtime.js 增加 matrix:dark-contrast，在暗色令牌下重跑对比度检查。

验收：

# 1) 令牌组存在且完整
grep -q "html.aa-dark" .design_library/aurora-admin/colors_and_type.css && echo "dark tokens OK"
node -e "
const css=require('fs').readFileSync('.design_library/aurora-admin/colors_and_type.css','utf8');
const m=css.match(/html\.aa-dark\s*\{([^}]+)\}/s);
if(!m){console.error('FAIL: 无暗色令牌组');process.exit(1)}
const n=(m[1].match(/--au-/g)||[]).length;
console.log('暗色令牌数:', n);
if(n<15){console.error('FAIL: 令牌数不足（预期 ≥15）');process.exit(1)}
"

# 2) 浏览器实测（关键验收）
# 打开 http://127.0.0.1:3311/site/index.html，切暗色模式，
# 逐个打开至少 10 个组件详情页，确认无「白底黑字残留」

浏览器实测项：

• 首页 / 总览 / 设计规范 / 组件详情 全部正常反色
• 任意 10 个组件演示页反色后对比度可读
• 截图对比（交付说明附 3 张暗色截图）

预期输出：

dark tokens OK
暗色令牌数: 20+（预期 ≥15）

失败判据：

• 暗色令牌数 < 15
• 任一页面出现"白底 + 白字"或"黑底 + 黑字"
• 对比度脚本报出 < 4.5:1 的文字

已知风险：79 个演示页的内嵌样式是硬编码过令牌化的（v1.4.0 完成），所以理论上改令牌就能全局生效 —— 这是 v1.4.0 打下的地基，本次直接受益。

---

S2-P6 · 跨端一致性自动验证 ｜ 预算 ~1 天 ｜ 优先级 P0

目标：能自动回答「H5 / React / Vue2 / Vue3 四个实现是否视觉一致」，并给出差异截图。

依据：G5。5 端 395 个文件，但从来没人验证过它们是否真的一致。契约里写的"各端视觉一致"是纯声称。

依赖：S1-P3（需要 CI 环境跑 Playwright）。

路径：

• tools/verify-cross-platform.mjs（新建）
• tools/render-harness/（新建，把 React/Vue 组件渲染成静态 HTML）
• tests/cross-platform-report.json（产出）

步骤：

1. 难点：React/Vue 组件需要构建才能渲染（.jsx/.vue 不能直接在浏览器跑）。 零依赖解法：
   • 方案 A：用 CDN 版 React/Vue（<script src="unpkg.com/react">）+ @babel/standalone 在浏览器里编译 JSX。缺点：依赖 CDN 可用性。
   • 方案 B：更推荐 —— 只做结构性比对而非像素比对。提取各端的 className 集合与 DOM 结构，比对差异。不要求渲染，纯静态分析。
   • 方案 C：混合 —— 结构比对为主，挑选 6 个核心组件做像素比对（核心组件的 CDN 依赖可接受）。
2. 推荐方案 B + 抽样 C：
   • 全部 79 组件：静态提取 class 集合与结构骨架，diff 各端
   • 6 个核心组件（button/input/select/table/card/modal）：CDN 渲染 + 截图比对
3. 输出报告：{ slug, platforms: {h5:[...classes], react:[...], vue2:[...], vue3:[...]}, diffs:[...], severity }

验收：

node tools/verify-cross-platform.mjs
node -e "
const r=require('./tests/cross-platform-report.json');
console.log('检查组件:', r.total);
console.log('完全一致:', r.identical);
console.log('有差异  :', r.differing);
console.log('差异样本:', JSON.stringify(r.samples.slice(0,3),null,1));
"

预期输出：一份报告，明确列出哪些组件的哪些端存在 class/结构差异。

失败判据：

• 脚本报错或无输出
• 报告里 total < 79
• 差异项没有具体说明（只说"不一致"而不给差异内容）

重要说明：这个任务的产出可能揭露一批真实的不一致。这不是失败 —— 是这项任务的价值。发现的差异应作为新任务包列出，不在本任务内顺手修（避免范围蔓延）。

---

S2-P7 · 行为断言 ｜ 预算 ~1.5 天 ｜ 优先级 P1

目标：测试从"元素存在"升级到"交互后发生什么"，覆盖点击/输入/键盘的真实行为。

依据：G8。当前 12 项/页断言多为结构性（元素存在、有 aria、对比度达标），没有任何一条验证"点了按钮会怎样"。

依赖：无。

路径：

• tests/_runtime.js（扩展断言引擎）
• tests/_behaviors.js（新建，行为断言库）

步骤：

1. 定义行为断言协议（在演示页里声明）：

   <button data-behavior="click-toggles-class:.aa-modal|is-open">打开弹窗</button>
   

2. 实现常见行为模式：
   • click-toggles-class:<selector>|<class> — 点击切换类
   • click-sets-attr:<selector>|<attr>|<value> — 点击设属性
   • input-updates:<selector>|<text> — 输入后状态变化
   • keyboard-activates:<key> — 键盘触发
   • focus-trap:<container> — 弹窗焦点锁定
3. 在 6 个核心组件（button/modal/select/input/table/tabs）的演示页里标注行为断言作为试点。
4. 断言结果并入现有报告结构（matrix:behavior:*）。

验收：

# 1) 行为断言库存在且语法正确
node --check tests/_behaviors.js && echo "syntax OK"

# 2) 6 个试点组件有行为断言
grep -l "data-behavior" frameworks/{Button,Modal,Select,Input,Table,Tabs}.html | wc -l
# 期望输出 6

# 3) 回归里出现行为断言
# 跑 _collect.html，检查 report.json 的 failureKinds 含 matrix:behavior:*

浏览器实测：点击弹窗按钮后，is-open 类被添加（观察 DOM）。

预期输出：

syntax OK
6

失败判据：

• 试点组件少于 6 个
• 行为断言在回归报告里不出现
• 断言只是"元素存在"换个名字（无实际交互逻辑）

---

S3-P8 · RTL 支持 ｜ 预算 ~2 天 ｜ 优先级 P1

目标：<html dir="rtl"> 时布局正确镜像，无错位。

依据：G7。逻辑属性 0 处，物理属性（margin-left 等）出现在 22 个文件。竞品 7 家里 3 家有 RTL。

依赖：S2-P5（暗色完成后改样式更安全，减少冲突）。

路径：

• frameworks/*.css（22 个含物理属性的文件）
• frameworks/*.html 内嵌样式
• .design_library/aurora-admin/colors_and_type.css（如需要在文档说明约定）

步骤：

1. 批量迁移物理→逻辑属性：

   物理	逻辑
   margin-left	margin-inline-start
   margin-right	margin-inline-end
   padding-left/right	padding-inline-start/end
   left / right（定位）	inset-inline-start/end
   text-align: left/right	text-align: start/end
   border-left/right	border-inline-start/end

2. 注意例外：图标方向类（箭头、返回）需要 transform: scaleX(-1) 而非属性迁移。
3. 写一个 RTL 演示页：site/scenario/user-management-rtl.html，用于人工验收。
4. 增加 RTL 断言：matrix:rtl-safe，检测是否还有物理属性的残留。

验收：

# 1) 物理属性清零
n=$(grep -l "margin-left\|margin-right\|padding-left\|padding-right" frameworks/*.css 2>/dev/null | wc -l)
echo "剩余物理属性文件: $n"
test "$n" -eq 0 && echo "RTL migration OK"

# 2) 逻辑属性已使用
grep -l "margin-inline\|padding-inline\|inset-inline" frameworks/*.css | wc -l
# 期望 ≥ 22

浏览器实测：user-management-rtl.html 加 dir="rtl"，确认布局镜像无错位（附截图）。

预期输出：

剩余物理属性文件: 0
RTL migration OK
22+

失败判据：

• 仍有物理属性残留
• RTL 下出现元素重叠/溢出
• 图标方向错误（如右箭头在 RTL 下仍指右）

---

S3-P9 · FAQ 页 ｜ 预算 ~1 天 ｜ 优先级 P2

目标：新增 #/faq 页，自动聚合 139 条 unknowns + 101 条 doNotInvent，形成可检索的问答。

依据：契约里已有 240 条结构化条目，现成素材没被利用。Ant Design 每组件 FAQ 是行业惯例。

依赖：无。

路径：

• site/app.js（新增 renderFaq）
• site/index.html（导航加 FAQ 链接）
• site/i18n.js（文案）

步骤：

1. build-site.ps1 已把 contract 注入 data.js（字段 unknowns / doNot），直接消费即可。
2. 渲染两种视图：
   • 按组件：每个组件列出它的 unknowns（"规范未明示"）与 doNotInvent（"不要自行发明"）
   • 按分类：把相似的 unknowns 聚类（如"最大宽度""省略方式"跨多个组件出现）
3. 加搜索过滤（复用 _runtime 的思路，纯前端）。

验收：

# 1) 路由可达
curl -s http://127.0.0.1:3311/site/index.html | grep -q 'href="#/faq"' && echo "nav OK"
# 2) 数据完整注入
node -e "
const d=require('./site/data.json');
const u=d.components.reduce((s,c)=>s+((c.contract&&c.contract.unknowns)||[]).length,0);
const dn=d.components.reduce((s,c)=>s+((c.contract&&c.contract.doNot)||[]).length,0);
console.log('unknowns:',u,'doNotInvent:',dn);
if(u<139||dn<101){console.error('FAIL: 契约数据缺失');process.exit(1)}
console.log('data OK');
"

浏览器实测：#/faq 显示 79 个组件的条目，搜索"宽度"能过滤出相关项。

预期输出：

nav OK
unknowns: 139 doNotInvent: 101
data OK

失败判据：条目数少于 139/101，或页面空白。

---

S4-P10 · Figma 资源 ｜ 预算 ~2 天 ｜ 优先级 P2

目标：产出可导入 Figma 的变量集与组件描述，设计师能直接用同一套令牌。

依据：竞品标配 Figma/Sketch 资源。本项目已有 site/tokens/figma.json（Tokens Studio 格式），但没有 Figma Variables 原生格式。

依赖：S1-P2（需稳定的令牌导出管线）。

路径：

• tools/export-figma.mjs（新建）
• dist/figma/（产出）

步骤：

1. 产出 Figma Variables JSON（与 Tokens Studio 格式不同，是 Figma 原生 API 格式）：
   • 色彩变量 → { "color": { "brand": { "type": "COLOR", "value": {...} } } }
   • 数值变量（间距/圆角/字号）→ FLOAT
   • 建立 Light / Dark 两种 mode（呼应 S2-P5）
2. 产出组件清单 Markdown（供设计师建组件时参考）：每个组件的变体维度 + 尺寸 + 状态。
3. 写导入说明（dist/figma/README.md）。

验收：

node tools/export-figma.mjs
node -e "
const v=require('./dist/figma/variables.json');
const colors=Object.keys(v.color||{}).length;
console.log('色彩变量:', colors);
console.log('模式:', Object.keys(v.modes||{}).join(', '));
if(!v.modes||!v.modes.Dark){console.error('FAIL: 缺少 Dark 模式');process.exit(1)}
console.log('figma export OK');
"

预期输出：

色彩变量: 24+
模式: Light, Dark
figma export OK

失败判据：无 Dark 模式、变量数明显少于令牌数、JSON 不符合 Figma Variables 结构。

---

S4-P11 · 模板页库 ｜ 预算 ~2 天 ｜ 优先级 P2

目标：从 1 个场景页扩展到 5 个典型后台页面模板，展示组件组合用法。

依据：现有 site/scenario/user-management.html 是唯一的组合示范。模板页是"能否直接用"的关键 —— 用户要的不是组件，是页面。

依赖：无。

路径：site/scenario/*.html（新增 4 个）

步骤：

1. 选定 4 个典型场景（覆盖不同组件组合）：
   • login.html — 登录页（输入类组件 + 表单校验）
   • dashboard.html — 数据看板（图表 + 指标卡 + 表格）
   • order-list.html — 列表管理（表格 + 筛选 + 分页 + 批量操作）
   • settings.html — 设置页（Tab + 表单 + 开关组）
2. 每个模板页只用现有令牌与 components.css，纯 HTML + 原生 JS（零依赖）。
3. 加到首页入口与 sitemap。

验收：每个模板页在浏览器实测可交互（筛选、分页、提交有反馈），附截图。

失败判据：页面白屏、交互无效、用了非项目内的样式。

---

S4-P12 · 版本发布流程 ｜ 预算 ~1 天 ｜ 优先级 P3

目标：有明确的 SemVer 发布流程与自动化。

依赖：S1-P2。

步骤：

1. tools/release.mjs：从 CHANGELOG 提取版本 → 更新 package.json → 打 tag → 提示推送。
2. 文档化到 CONTRIBUTING.md。

---

四 · 风险登记

风险	影响	缓解
约束冲突：CI 需要 Playwright，但"零依赖"	中	明确区分运行时依赖（保持零）与构建/测试依赖（可引入 devDependencies），并在 README 写清
S2-P6 暴露大量跨端不一致	中	已在任务包里说明"发现即价值"，差异作为新任务列出，不顺手修
暗色反色后视觉倒退	中	强制对比度脚本验证 + 人工截图验收
RTL 迁移破坏现有布局	中	迁移后跑八次回归；逐文件比对渲染截图
data.js 拆分影响 For Agents 承诺	高	明确要求 data.json 保持完整，只拆 data.js
用户未确认许可证类型	中	默认 MIT 并在交付说明标注"如需变更请告知"

---

五 · 验收总纲

任一任务包完成，必须同时满足：

1. 给出验收命令的完整输出（不是"我以为跑过了"）
2. 跑八次回归：100% / 0 失败 / 0 超时
3. CHANGELOG.md 有对应条目（[Unreleased] 下）
4. 本文件对应任务包下追加 ✅ 完成于 <commit-hash>
5. 若发现新问题：写成新任务包追加到本文件，不在原任务里顺手修

---

附 · 优先级总表

ID	任务	阶段	优先级	预算	依赖
P1	LICENSE	S1	P0	10 min	用户确认类型
P2	npm 分发	S1	P0	2 h	P1
P3	CI 回归	S1	P0	1.5 h	—
P4	data.js 瘦身	S1	P0	3 h	—
P5	暗色模式	S2	P0	1 d	P4
P6	跨端一致性验证	S2	P0	1 d	P3
P7	行为断言	S2	P1	1.5 d	—
P8	RTL	S3	P1	2 d	P5
P9	FAQ 页	S3	P2	1 d	—
P10	Figma 资源	S4	P2	2 d	P2
P11	模板页库	S4	P2	2 d	—
P12	版本发布流程	S4	P3	1 d	P2

建议执行顺序：P1 → P3 → P4 → P2 → P5 → P6（前六个是「可交付」与「可信」的地基）