代码治理与评审约束¶
本规范定义设计系统在代码层的落点、使用边界与评审约束，用于防止视觉语言再次回到页面级碎片化状态。它既是设计系统的治理规则，也是前端 PR 的统一检查清单。
1. Source of Truth¶
1.1 视觉源头¶
- Token 源头：
web/app/globals.css - 全局字体与主题入口：
web/app/layout.tsx - 共享原语源头：
web/components/ui/ - 页面模板源头：
docs/handbook/web-design-page-templates.md
1.2 基本原则¶
- token 只在 token 层定义。
- 共享组件只在原语层定义主视觉实现。
- 页面层只做组合与内容编排。
2. 允许与禁止的实现模式¶
2.1 允许¶
- 使用语义 token class 或受控 CSS variable。
- 在共享原语中新增经过审查的 variant。
- 在页面中通过布局 utility 组合共享组件。
- 使用 Handbook 中已记录的例外模式。
2.2 禁止¶
- 在页面 JSX 中直接写品牌蓝或品牌状态色 raw hex。
- 在页面中新增
text-[10px]、text-[11px]作为长期样式。 - 在页面中复制新的 button / input / card / badge 样式实现。
- 在多个页面中各自定义不同的 shadow / ring / radius recipe。
- 在 dense data 页面无控制地使用玻璃、辉光和装饰性动画。
3. 例外申请流程¶
如需新增 token、组件变体或页面模板偏离，必须回答以下问题：
- 当前规范为什么无法满足需求。
- 新增语义是否会被多个页面复用。
- 是否应提升到 token / primitive / template 层，而不是页面局部解决。
- 是否同步更新对应 Handbook 文档。
如果无法清晰回答以上问题，应默认不新增例外。
4. PR Checklist¶
涉及 UI 改动的 PR 至少应检查：
- 是否使用了已有 token 和共享原语。
- 是否引入了新的 raw hex、局部阴影、局部 micro typography。
- 若改动了 token 或 primitive，是否同步更新 Handbook 文档。
- 是否补充了必要的桌面与移动端截图。
- 是否验证了 focus-visible、键盘可达性和 reduced-motion。
5. 自动审计建议¶
首期建议增加以下轻量检查：
- 搜索 JSX / TSX 中的品牌色 raw hex
- 搜索
text-[10px]、text-[11px] - 搜索局部
focus:ringrecipe 是否重复 - 搜索页面级
boxShadow与 inlinestyle.color是否越界
这些检查初期可通过 grep 规则维护，后期再升级为脚本或 lint 规则。
6. 人工评审门槛¶
所有 UI 相关 PR 都应进行以下人工评审：
- 视觉一致性评审：是否仍符合统一设计语言。
- 可读性评审：dense data 页面是否因品牌化而降低扫描效率。
- 无障碍评审：对比度、焦点态、键盘导航是否完整。
- 抽象层级评审：改动是否发生在正确的 owner abstraction 上。
7. 迁移期 Guardrails¶
在设计系统落地期，必须遵守以下 guardrails：
- 优先在 token / primitive 层修正问题，不用页面热修补代替系统修复。
- 不在 light-first 改造期间顺手重做 dark mode。
- 不因为局部 deadline 放弃设计系统回收，除非文档记录为临时例外。
- 若某页面仍需保留旧样式，应明确标记迁移债务，而不是隐式遗留。
8. 设计系统所有权与评审节奏¶
建议至少明确以下角色：
- Design System Owner：维护 token、组件、模板与规范文档
- Frontend Approver：评估实现层是否遵守规范
- Product / UX Reviewer：确认体验方向没有偏离产品目标
建议的治理节奏：
- 每次 token 变更同步更新文档
- 每次 primitive 结构变更同步更新组件规范
- 每个里程碑做一次 drift audit，确认是否出现新的页面级视觉分叉
9. 文档与实现同步要求¶
以下变更必须同时修改 Handbook：
- 新增或废弃 token
- Button / Input / Card / Sidebar / DataTable 等核心原语发生结构性变化
- 页面模板新增或改变主区域划分
- 评审规则和自动审计规则发生变化
如果代码已变而文档未更新，应视为设计系统变更未完成。