Skip to content

ADR-032-frontend-design-system-tokens.md

Latest commit

 

History

History
32 lines (23 loc) · 3.16 KB

ADR-032-frontend-design-system-tokens.md

File metadata and controls

32 lines (23 loc) · 3.16 KB
Raw

ADR-032：前端设计系统与 token 层落地

状态：已接受（2026-09-11） 关联：前端重设计规格 · theme.md · ui-ux-system.md

背景

前端 131 个非测试组件全部使用内联 style：实测 2,256 处 style={{、仅 3 处 className、0 个 CSS 变量、88 个不同 hex。 后果是不逐文件改组件代码就无法调整任何样式 —— 布局重排与动效落地都被这一条前置阻塞。 同时 docs/product/theme.md 规定的「颜色值只出现在 token 定义处」全库 0 处遵守。

决策

  1. 建立 token 变量层，前缀统一 --ed-，单一真源为 app/scripts/gen-tokens.mjs，产物 app/src/ui/tokens.css 与 app/src/ui/tokens.gen.ts 均为生成物，手改由漂移测试判失败。
  2. 色阶采用「纸 + 墨」双档体系（视觉方向 C 活页）：亮为主档、暗为「夜读」第二档，两档各给一值 —— 因同一颜色两档对比度差可达 4 倍。
  3. 四档墨度编码确定度（材质语言 D 显影）：ink-4 未确认 / ink-3 已重打分 / ink-2 已确认 / ink-1 已改写。
  4. 可及性裁决：以阅读面 --ed-bg-surface 为基准 —— ink-2 ≥11:1、ink-3 ≥4.5:1、ink-4 允许 3:1（实测：亮 11.42/5.13/3.22，暗 11.41/5.82/3.22）。ink-4 的例外仅限过渡态，且必须满足：不得承载唯一关键信息、任何交互即升到 ink-2、进入审校模式时全体升到 ≥4.5:1。
  5. z-index 六档标尺（t1=10 吸顶 / t2=100 常驻面板 / t3=200 锚定弹层 / t4=300 Modal+遮罩 / t5=400 Modal 内嵌 / t6=500 Toast），替代现状 32 文件 45 处硬编码的 17 个不同值。
  6. 图标语言为自绘线性 SVG（24 网格 / 描边 1.75 / 小圆角 / currentColor），替代 310 个 emoji（跨平台字形不一致、无法语义着色、基线抖动）。

后果

  • 正面：样式首次可集中调校；对比度可被测试守护；图标可语义着色；后续批次不必逐文件改内联对象。
  • 负面：存量 2,256 处内联 style 需按域逐步迁移（批 4），迁移期两套写法并存。
  • 风险：ink-4 的 3:1 例外可能被误用 —— 由本 ADR 第 4 条三条约束 + review 检查兜底。
  • 实证：色阶初稿中 --due 亮档取 #B26A12，实测对纸底仅 4.06:1、对面 4.23:1，低于正文 4.5:1 线，而它要承载「记忆语义」文字（如「3 天后」）。已修正为 #A05F10（4.86 / 5.07）。该错误由本 ADR 要求的对比度测试在写测试阶段捕获 —— 这正是把纪律机器化的价值。

替代方案与否决理由

  • 继续用内联 style + 约定色板：否决。约定无法被测试守护，且 88 个 hex 已证明约定会漂移。
  • 引入 Tailwind 或 CSS-in-JS：否决。需要新依赖与构建改造，而本项目已有「脚本生成 CSS」的既有模式（gen-mark-css.mjs）可直接复用，成本更低。
  • 只建 CSS 变量、不做生成器：否决。无漂移守卫时 CSS 与 TS 两份数据必然分叉（现状 md/TS 双写已有先例问题）。