visual-acceptance

name	visual-acceptance
description	UI/视觉改动交付前的终验方法论——多主题截图矩阵复现、像素真值判据链、CSS 层叠陷阱、布局漂移审查、before/after 存证。当视觉改动需要验收（而非实现）时使用：交付前最后一环，回答「看得见的部分真的对吗」。
triggers	["视觉验证|视觉回归|视觉终验|视觉验收|截图对比|截图存证|三主题|收灯验收|visual.?regression|visual.?acceptance|screenshot.?diff|pixel.?check"]

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 层叠来源

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

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 推走的孤儿元素）