UI 规范审计器（ui-spec-auditor）
概述
以静态分析方式审计前端代码的 UI 规范一致性，输出可交付的 HTML 看板。核心价值在两点：
- 设计规约可插拔：规约是外部 JSON 文件，换一份规约就换一套标准，不限于任何特定风格。
- 无规约也能用：
infer模式从代码反推设计令牌，标记离群值并导出建议规约，让没有设计系统的项目立刻获得基线。
审计器只读，从不修改源文件；所有修复决策由使用者做出。
何时使用
- 需要检查项目是否真的落地了设计系统（而非只是写了设计规范文档）
- 重构或 UI 升级后，需要量化「还剩多少历史包袱」
- 接手陌生项目，需要快速摸清它的实际设计令牌与混乱程度
- 需要把「去动画化」「黑金配色」这类主观风格要求转成可验证的客观条目
- 需要在多端（Web + 小程序）之间核对视觉一致性
工作流
第 1 步：确定目标与模式
确认待扫描路径（目录或单文件），然后判断模式：
| 情形 | 模式 | 说明 |
|---|---|---|
项目已有 .ui-spec.json 或用户提供规约 |
preset |
做合规校验 |
| 用户描述了具体规范但无规约文件 | preset |
按其描述生成规约 JSON，再用该规约运行 |
| 项目没有设计系统 / 用户想摸底 | infer |
反推令牌 + 离群值分析 |
| 不确定 | auto（默认） |
有 --spec 则 preset，否则 infer |
不确定时直接用 auto。若用户描述了具体规范（如「主色 #d4af37，禁止动画」），先按其描述生成一份规约 JSON 存入项目根目录，再用 preset 模式——这样结论更可辩护，也让规范本身沉淀为资产。
第 2 步：选择设计规约
- 内置预设：
assets/presets/black-gold.json（黑金新中式 + 玻璃拟态 + 去动画化） - 自定义：复制预设后按
references/rule-catalog.md第九节改写，或用infer模式导出建议规约再人工复核
生成自定义规约后建议存为项目根的 .ui-spec.json，便于复用与版本管理。
第 3 步：运行审计
# 自动模式（推荐首次使用）
python scripts/audit.py --path /path/to/project --json audit.json --html audit.html
# 指定规约
python scripts/audit.py --path /path/to/project --spec .ui-spec.json --html audit.html
# 反推模式并导出建议规约
python scripts/audit.py --path /path/to/project --mode infer --html audit.html --emit-spec .ui-spec.json
# 只扫特定类型、加 CI 门禁
python scripts/audit.py --path src --ext .vue,.scss --fail-under 80 --json audit.json
常用参数：--ext 限定扩展名、--exclude-dir 追加排除目录、--rpx-ratio 调整 rpx 换算比（默认 0.5，对应 750 设计稿）、--fail-under 未达标时退出码为 2。
第 4 步：解读与交付
- 读取脚本 stdout 摘要与
audit.json（结构见下） - 用
present_files展示 HTML 看板 - 在回复中给出结论而非复述数据：总分与等级、最严重的 2-3 个系统性问题、优先修复的文件 Top 3、以及一条「最高杠杆」的收敛建议
解读要点：
- 看维度分，不看问题总数。问题多可能只是项目大，密度分才是可比指标。
- 优先处理 high：通常是对比度、无限循环动画、超长过渡这类硬伤。
- 离群值比违规数更值得关注：
infer模式下某个颜色只出现 1-2 次，往往意味着「这里当时随手写的」。 - 单文件问题密集通常说明该文件是被反复修改的核心页，收敛它收益最高。
输出结构（audit.json）
meta 路径 / 模式 / 规约名 / 文件数 / 行数 / 耗时
score total、grade（A-E）、dimensions[]（key/label/score/weight/issues）
summary high / medium / low / info 计数
findings[] id、dimension、severity、file、line、snippet、message、suggestion
fileRanking[] 按权重倒序的问题文件
distribution 颜色 / 字号 / 间距 / z-index 的频次分布
suggestedSpec infer 模式下反推的建议规约
规则体系
共 19 条 preset 规则 + 4 条 infer 规则，分为 6 个维度：色彩、动效、排版、间距、层级、平台适配。
完整判定口径、可配置参数与已知局限见 references/rule-catalog.md——解释结论或用户追问「为什么报这一条」时查阅该文件。
边界
- 只做静态分析：不渲染页面、不解析 CSS 级联结果、不做截图比对
- 不识别 CSS 变量的间接赋值链与 CSS-in-JS 动态表达式
- 对比度仅在前景与背景同处一个选择器块时可判定
- 结果需结合设计意图判断：审计器报告「偏离规范」，不等于「这里写错了」
参考资源
scripts/audit.py— 审计引擎，纯标准库、跨平台assets/presets/black-gold.json— 内置规约预设，也是自定义规约的模板assets/report-template.html— HTML 看板模板（黑金配色、零动画）references/rule-catalog.md— 规则目录与判据细节
