# visual-baseline（L4 视觉回归基线）

> 由 `sdd-flow-kit` 在 PRD run 脚手架时创建。与 `source/` 下 PRD 原型图配合使用。

## 用途

- 存放 **裁剪后的 UI 基线截图**（可选；也可直接引用 `source/**/image_N.png`）
- `05-验收清单.md` 中 `visual` 类型 AC 须在「验收标准」写明基线路径，例如：
  - `列表页与基线 source/adi-v234/image_1.png 布局一致（diff≤2%）`
  - `详情抽屉与 visual-baseline/finance-detail.png 一致（diff≤2%）`

## demo/（演示站截图，实现前强制）

- `demo/*.png`：演示站列表/详情等关键屏截图，是**视觉 SSOT**
- `demo/demo-styles.json`：由 `npx sdd-flow-kit demo-styles-extract` 生成的**样式基线**（间距/字号/行高/圆角/色值等数值）
- 使用顺序（16-演示布局合约）：
  1. `demo-layout-capture` 创建目录 → 2. 截取关键屏 → 3. `demo-layout-analyze` 填合约 → 4. `demo-styles-extract` 生成样式基线 → 5. 闭合合约过 `gate layout-contract-ready`
- **Apply 阶段强制**：实现任一页面/区块前必须 `Read` 对应截图 + `demo-styles.json`；间距/字号/颜色以数值基线为准，禁止用文字近似描述替代

## E2E 要求（v1.3.21 门禁）

```typescript
await expect(page).toHaveScreenshot("finance-report-list.png", {
  maxDiffPixelRatio: 0.02,
});
```

- 须与 `[AC-xx]` 同处一个 test 块
- **禁止**仅用 `page.screenshot()` 代替 `toHaveScreenshot`
- Playwright 快照目录默认：`e2e/finance/*.spec.ts-snapshots/` 或与基线名一致

## 门禁

`assess-visual-regression.mjs` 在 deliver 阶段校验。

豁免：`tasks.md` 写 `VISUAL_REGRESSION_EXEMPT: <原因>` 时：

- 原因须 **≥12 字**，且含 `用户确认` / `人工签收` / `Intentional` / `无稳定字体` / `CI不稳定` 等可审计语义
- **不能**用豁免跳过「有原型图必须有 visual AC」；visual 优先级仍须 P0/P1
- 合格豁免仅跳过 `toHaveScreenshot` 绑定检查

环境变量：`OPSX_SKIP_VISUAL_REGRESSION=1`（紧急全跳过，不推荐）