cyl19970726 Frontend Product Design · 前端产品设计与实现
心智模型（先内化，再动手）
1. 前端是三条流之间的翻译，禁止跳译
合同流（文字·意图） → 感知流（图·方向） → 规格流（测量值·实现） → Owner 眼（验收）
Phase 0 Phase 1 Phase 2 → 3 Phase 4
每两条相邻流之间必须有显式翻译产物：合同是意图的文字化、设计图是合同的可视化、 规格是图的测量化。跳级即失败：
- 图 → 直接写代码 = 每个 agent 各译一遍，65 个 reviewer 65 种"差不多"（实测）
- 实现 → 反补设计图 = 给犯罪现场补合同，验收失去独立参照系
- 感觉 → 直接调 CSS = 改没渲染都不知道（@layer 致盲：preflight 静默 nullify 全表 margin/padding/border，多轮"调整"从未生效）
2. 判断权归属表（本 skill 的第一约束）
| 判断 | 唯一有资格的来源 |
|---|---|
| 方向/风格好不好看 | Owner 的眼睛（对实际截图/候选图） |
| 落地没落地（元素在不在、值对不对） | 机械测量（测试 / 像素采样 / computed style） |
| agent 自己 | 翻译者 + 验证者。永远不是裁判 |
agent 输出里出现"looks good / 符合设计 / 视觉效果不错"而无 Owner 批注 = 违规信号。 实测代价：65 个 agent reviewer 的自判 PASS 被 Owner 证伪 ≥17 次。
3. 设计是一个会过期的引用
设计图是 reference 不是 constant。规则：单一真源（一处存活，如 Notion）、 选定即冻结、落选即显式标记 DEAD、变更留 changelog、代码仓只放指针 （链接），不放设计图源文件。失效不传播 = 全队朝作废目标施工（实测：v3 作废图 留在 git 历史被当作合同用了一年）。
4. 诚实边界：每个 UI 元素只有三种出身
数据有出处（字段存在） / 静态文案（可写死） / needs-backend（立后端任务）
设计期就在「元素→数据映射表」里标注出身；实现期禁止伪造中间态——没有字段的 元素缺省并具名，绝不发明占位数据、占位因果、占位状态。needs-backend 项必须成为 可追踪的后端工作项，不许在"残余清单"里躺平。
5. 验证的单位是渲染结果，不是代码改动
"改了 CSS" ≠ "渲染了"。验收只看：截图、像素采样、computed style、精确 revision。 材质类结论必须有像素级证据（例：白卡 #ffffff vs 画布 #fffefb 差 1/255 = 不可见， 无论规则写没写）。
6. 规格必须可重生
spec 由脚本化测量产出，不是手工感觉笔记。可重生才可校验、才不怕丢失、 才能在新设计图进来时快速再版。存放分工：脚本实体入仓（可运行、可复测）， spec 文档存设计真源页，真源页放脚本的仓内链接（脚本无法"同存"于 Notion）。
五阶段流水线
Phase 0 文字合同 ──GATE: Owner 确认合同──▶
Phase 1 出稿探索 ──GATE: Owner 选定方向+冻结──▶
Phase 2 测量成规格 ──GATE: 数据可行性标注完──▶
Phase 3 对照规格实现 ──GATE: 机械验证全绿+渲染证据──▶
Phase 4 Owner 视觉验收 ──批注→回写 spec/清单→再迭代──▶ 交付
Phase 0 · 文字合同（不生成任何图）
产出物（文字，存设计真源处）：
- 范围与非目标（明确不做什么）
- 数据可见性/权限规则（谁能看到什么，结构性 absent 而非隐藏）
- 布局合同（栏结构、滚动归属、首视口必须可见的内容、sticky 元素）
- 组件清单（页面由哪些区域/组件构成）
- UX 行为规则（见下文「交互行为基线」）
- 文案语调（如 quiet operations：陈述事实、无感叹、无营销词）
闸门：Owner 确认合同文字。没确认不出稿。
Phase 1 · 出稿探索（生成图片的唯一合法时机）
图是决策输入，不是交付物。
- 只从 Phase 0 合同生成，把合同喂进生成 prompt；禁止自由发挥
- 一次出多候选，Owner 选的是方向（风格/密度/层级），不是像素
- 选定那一刻：冻结进设计真源（唯一 authority）+ 落选者显式标记 DEAD
- 两个禁止时机：① 实现已存在后"照实现补图"（合同变追认）；② 合同没变却 反复重新生成（每次重生成都是隐性合同变更）
- 出图方式不限：方向选定的本质是冻结唯一真源——agent 生成、Owner 供图、 外部工具（Figma 等）均可；无出图能力时以 Owner 供图直接进冻结，不许卡死
Phase 2 · 测量成规格（不许照图直接写代码）
把冻结图测量成文字规格，全部标注 [实测]（采样值）或 [推导]（图未展示、
按信条推）：
- 调色板（像素采样：canvas/卡片/发丝线/墨色/强调色/状态色）
- 字阶（量字高换算：标题/正文/标签/meta 的 size·weight·color）
- 几何（栏宽、padding、行节奏、圆角——按基准宽度等比换算）
- 组件形态逐条（含 default/hover/focus/selected/disabled/empty/loading 全状态）
- 元素→数据映射表：每个元素标 有出处（字段名）/ 静态文案 / needs-backend； needs-backend 立后端工作项
产出：visual-spec-<版本>.md + 测量脚本（同存）。信条级原则（如"平面、发丝线、
留白分隔、强调色仅主动作"）写在 spec 头部，后续所有推导项不得违反。
Phase 3 · 对照规格实现 + 机械验证
- 逐元素清单驱动（每个元素一行：实现状态），一次改完一个维度集合再送验， 不倒退回"改一点送一次"
- 每批必跑项目机械验证（typecheck / lint / 项目 browser-check），断言强度 只许升不许降；引用被有意改动元素的断言同步更新并说明
- 渲染验证：改完用像素采样/computed style 证明生效，不看 diff 下结论
- 截图证据绑定精确 revision（exact SHA 进文件名/manifest）
- 铁律：不伪造数据、不自判视觉、最小改动、不动冻结接口
Phase 4 · Owner 视觉验收
- 把实际截图和冻结参照图同尺度并排交给 Owner（可附 montage）
- 批注 → 回写 spec/清单 → 下一轮；残余项全部具名+附原因（无数据/超范围/ 设计示例文案）
- PASS 只有一个来源：Owner 对截图的明确批准。验收报告只交"清单落地证据
- 具名残余"，不写视觉结论
规模分档（防止"流程太重→绕行→旧病复发"）
完整管线适用于标准档与新模块档；微调档（不新增 surface/数据元素/组件、
不动布局合同）可免合同与 spec 全量编制——但三条铁律无豁免：渲染证据、绑定
revision、Owner 批注。档级判据与留痕要求见 references/acceptance-and-falsification.md §7；
拿不准 = 标准档。
交互行为基线（UX 合同通用条款）
- 权威写：写操作等权威回执，禁止乐观假成功；回执失败保留输入并明示
- stale/error/loading：数据过期或刷新失败时写操作禁用并说明原因；error 保留 last-good 只读视图
- 危险动作：close/retire/delete 类给确认或明确 danger 视觉，不一键即发
- 键盘与焦点：可交互行可 Tab 到达、Enter/Space 激活、focus-visible 全表统一 形态；弹层 Esc 关闭+焦点圈闭+关闭后焦点还原
- 空态：给"为什么空+能做什么"，不给裸空白
组件登记表（防实现分叉）
每个项目维护一页 registry：组件 / 用途 / 何时复用 / 何时允许新增。 新建 primitive 前必须查表；同一需求的第二个实现出现 = 分叉信号，先合并 再继续。改共享 primitive 要查全部调用点。
Spec 变更管理
- 本 skill 语境下 spec 只有一件产物：Phase 2 的
visual-spec-<版本>.md（含元素→ 数据映射表）；它只在设计真源一处存活（如 Notion），仓内只放链接 - 任何修改在真源页留一行 changelog（日期/改了什么/为什么）
- 设计图换代时：新图冻结、旧图标 DEAD、spec 重新测量再版（版本号递增）
失效模式表（签名 → 检测 → 处置）
| 失效 | 检测 | 处置 |
|---|---|---|
| 作废设计继续生效 | 设计源有多个版本并存/无唯一 authority | 冻结唯一真源，旧版标 DEAD |
| 样式"改了没渲染" | computed style/像素采样 ≠ 预期 | 查层叠（@layer/preflight/优先级），修根因 |
| agent 自判视觉 PASS | 报告出现 PASS/符合设计/视觉达标 字样且无 Owner 批注引用 |
机械打回（无需进一步阅读），改交落地证据清单；合法结论词仅 no-blocking-findings / findings(listed) |
| 无数据伪造 | 元素映射表有缺口却已"实现" | 删伪造，转 needs-backend 工作项 |
| 实现分叉 | 同一组件 ≥2 个私有实现 | 合并进 registry 的 canonical 件 |
| 验收粒度错误 | 只看 diff/测试，没看渲染 | 补像素/截图证据再下结论 |
工具箱与参考文件（references/）
通用流程的支撑文件，按需加载，不要全量预读：
references/measurement-toolbox.md— 测量与渲染验证工具箱（Phase 2/3 必用）： 像素采样、几何测量、并排 montage、层叠/产物根因排查五步法、证据绑定约定、 round 间差异定位。全部脚本化、可复测references/contract-and-spec-templates.md— Phase 0/2 产出模板：产品合同 （能力/journey/surface 正当性/coverage 标签/元素→数据映射/needs-backend 立项区）、 visual-spec 模板（信条/色板/字阶/几何/组件全状态）、组件登记表模板、 小工件存放位置统一约定references/acceptance-and-falsification.md— Phase 3/4 验收纪律：判断权词表 （机械打回规则）、硬不变量 vs 视觉诊断双轨、分层闸、失效触发器、评审失效 黑名单、证据包清单、规模分档
与本文件冲突处以本文件为准。
本仓适配（multi-agent-harness）
- 机械验证：
pnpm exec tsc -p apps/agent-dashboard/tsconfig.json --noEmit - 证据捕获：
AGENT_WORKSPACE_EVIDENCE_DIR=<dir> [FIRM_BUILD_GIT_REV=<40位sha>] node apps/agent-dashboard/tests/agent-workspace-browser-check.mjs（fixture 七帧 + 移动视口断言） - 证据目录
.visual-evidence/（gitignored）；冻结接口apps/agent-dashboard/src/model/roleViews.ts（类型只读）；设计真源在 Notion