docs(design): 设计真相源分层治理落地(原型漂移拍板)

- CLAUDE.md 新增「设计真相源分层」强制规则:L1 设计系统层原型单源不变;
  L2 屏级三态(同步/快照/代码先行);L3 新屏仍 design-first;漂移改定期体检
- CONTRACT 块 4 加「真相源」列(14 屏同步 / register 快照),新增代码先行
  屏小节(授权管理面板/购买卡/官网 checkout 等,不反向补原型)
- screens.mjs 注释明确只登记「同步」态屏,与 CONTRACT 互为镜像
- 附带体检:golden 84 用例全绿(failures 264 张陈留物已清);
  fidelity 36 屏×主题全部阈内(≤8%);check-ds 12 道闸全过

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JJ1g8XV1YhhmHRzhwWEW7o
This commit is contained in:
wangjia
2026-07-04 06:56:17 +08:00
parent e022494f63
commit e0fdb8c12f
3 changed files with 53 additions and 20 deletions
+12
View File
@@ -254,6 +254,18 @@ cd client && flutter test
- 使用 `dart:io``Platform` 类前,必须先检查 `kIsWeb``import 'package:flutter/foundation.dart'`
- Web 平台不支持 `dart:io`,直接使用会在 Web 构建时崩溃
### 设计真相源分层(原型漂移治理,2026-07-04 拍板)
原型(`.superpowers/prototype/`)与真实页面**不追求全量永久同步**,按层分治:
- **L1 设计系统层**`tokens.css` / `atoms.css` / `mobile-atoms.css` / `icons.js` + `index.html` 登记):原型是**单一真源**。新增颜色/组件/图标必须**先登记原型再同步**代码与官网(如 `web/_includes/icons.njk`)。闸:pre-commit `check-ds.mjs` 12 道(本地钩子,新机器先跑 `sh scripts/hooks/install.sh`+ 代码侧 `client/tool/check_ds_code.mjs`
- **L2 屏级三态**(台账 = `design/CONTRACT.md` 块 4「真相源」列):
- `同步`:注册于 `tools/screens.mjs`,fidelity 像素闸生效。整屏改版须原型先行;小迭代改后跑 fidelity 确认阈内,超阈则同步原型或降级快照。
- `快照`:原型退役为历史参考,**golden + CONTRACT 文字规格为准**;小迭代只更 golden,**不回填原型**。
- `代码先行`:无原型屏,golden 为唯一像素基准。
- **L3 新屏/整屏改版**design-first 不变(原型 → CONTRACT → 实现 → fidelity 验收),建成后入 `同步` 态。
- **漂移体检**:不逐提交强制同步;大版本/整屏改版前跑 `node tools/fidelity.mjs`,按报告逐屏决定「重新对齐原型」或「降级快照」,结果回填 CONTRACT。
### 表格与列头筛选(ds 真相源)
- 列表屏统一 `DsTable``widgets/ds/ds_table.dart`toolbar+表格+pager 连成一卡),列定义 `DsColumn`,可筛选列走其列头漏斗(`filtered` 态高亮),可隐藏列走列设置菜单
- 不要在 toolbar 放独立筛选按钮,筛选入口内嵌列头或工具栏 `DsChip`