# Visual Acceptance

> UI/视觉改动交付前的终验方法论——多主题截图矩阵复现、像素真值判据链、CSS 层叠陷阱、布局漂移审查、before/after 存证。当视觉改动需要验收（而非实现）时使用：交付前最后一环，回答「看得见的部分真的对吗」。

- Skill: `huiliyi37/visual-acceptance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huiliyi37/visual-acceptance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huiliyi37/visual-acceptance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: huiliyi37 (https://skillmd.com/u/huiliyi37)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huiliyi37/visual-acceptance

---


# Visual Acceptance — 视觉终验方法论

你在任意项目中对 UI/视觉改动做交付前的最后一道审视。你可能没写这些代码，项目的主题系统、构建管道你也未必熟——但你必须给出「看得见的部分是对的」这个结论，且结论要有证据形状：截图矩阵、像素值、before/after 对照，而不是「应该没问题」。

> 分工界线：这是**验收**技能，不是实现技能。界面怎么做出来是实现者的事；
> 这里管的是做出来之后，交付前有没有人真的看过、看的方法对不对、证据留没留。

---

## Stage 1: 复现术——不起整个 app 的截图矩阵

完整跑起应用再人肉点到目标界面，慢且不可复跑。正确姿势是搭一个最小 harness：

1. **用生产构建的编译 CSS，不用源码 CSS。** 找到构建产物里的样式文件（`dist/`、`build/`、`.next/` 等），复制进 harness。源码 CSS 验的是近似，编译产物才是产品——预处理器、压缩、autoprefixer 都可能改变最终层叠。
2. **harness HTML 用真实类名复刻目标场景。** 从产品 DOM 里抄结构和 class，不要手写近似样式。before/after 同页并排——一张截图直接回答「改动好在哪」。
3. **主题 token 注入。** 读项目的主题定义（CSS variables JSON / theme 文件），用 playwright 的 `page.evaluate`（或等价手段）把变量批量设到根元素上，与产品的 theme-loader 同语义。
4. **多主题矩阵一个不能少。** 至少 light/dark 各截一张；若产品有半透明/玻璃/壁纸类主题，它是**可读性的极限测试**（半透明底 + 任意背景），必须在列。每主题 fullPage 截图。
5. **动画冻结成静帧。** shimmer/pulse 类动画用 `animation-play-state: paused` 加负值 `animation-delay` 钉在特征帧上，静态截图才可检。
6. **截图归档为交付资产。** 命名带日期与场景，放进项目的文档资产目录——它们是验收证据，不是临时文件。

## Stage 2: 像素真值判据链

目视会骗人，且两个方向都骗：真浅色的图能被显示管道渲成深色（读图工具伪影），真白的底能让人以为「没截到」（实为 CSS 层叠 bug）。判据链逐级下钻，**任何一级与上一级矛盾时，信下一级**：

```
目视 → PNG 像素值 → computed style → CSS 层叠来源
```

读像素（三点采样：角落/中部/目标区域）：

```bash
python3 -c "from PIL import Image; im=Image.open('shot.png').convert('RGB'); print(im.getpixel((10,10)), im.getpixel((640,400)), im.getpixel((640,780)))"
```

- 像素与目视矛盾 → 显示管道伪影，截图本身没问题，别为不存在的 bug 改代码。
- 像素证实异常但 computed style 正确 → 问题在渲染层之下，查层叠来源与合成（Stage 3）。

## Stage 3: CSS 层叠陷阱

- **`!important` 只向 `!important` 低头。** 产品 CSS 里的 `!important` 规则会静默压掉 harness/宿主环境的普通规则；对抗它需要同 specificity 的 `!important` 且源序更靠后。debug 时单独设 class 一切正常、组合路径才踩中——层叠问题的典型形状。
- **宿主底色假设要显式补齐。** 产品若假设「外壳提供背景」（透明窗体、iframe 宿主、系统壁纸垫底），harness 必须显式补一层底，否则截图里的白/黑是**环境缺失**，会被误判成产品缺陷（或掩盖真缺陷）。

## Stage 4: 布局漂移审查

typecheck 与单元测试都不报的布局问题，静态截图审查一眼现形。逐行扫截图里每个小元素的**归属感**——它看起来属于谁：

- flex 容器里 `flex: 1` 的元素会把后续兄弟推到行尾。语义上「紧跟」主元素的小标识（序号、徽记、计数）必须**嵌进主元素内部**，不能做兄弟节点。
- 同一 DOM 模式在不同 flex 上下文中行为不同——一处对不代表处处对，每个使用场景各截一张。

## 收灯清单

全部满足才算验收通过：

- [ ] 多主题矩阵截齐，半透明主题下所有新元素可辨、可读
- [ ] before/after 同页对照存在，能一图回答「好在哪」
- [ ] 目视存疑处有像素值证据（不是「看着像对的」）
- [ ] 截图归档进项目文档资产目录，命名可溯源
- [ ] 布局归属感逐行扫过（没有被 flex 推走的孤儿元素）