visual-qa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: visual-qa — workflow tự-kiểm thị giác (capture → diff → judge → fix → re-verify)

Skill: visual-qa — 视觉自检工作流（capture → diff → judge → fix → re-verify）

Vì sao tồn tại: agent sửa UI rồi tự khen là sai lệch có hệ thống (failure
ui-pass-without-full-visual-review
). Ảnh chụp ra mà không ai mở = như chưa test. Workflow này thay "agent tự nhìn rồi tự cho pass" bằng ba tầng kiểm độc lập, trong đó hai tầng là máy.
Quyết định 13/07/26 (từ /last30days): ngành chỉ có MỘT thứ đã chín cho UI-do-AI-sinh — baseline snapshot + pixel diff (
argos-ci/argos
: "detects unintended visual changes"; Playwright
toHaveScreenshot
). Tầng "LLM-judge chấm screenshot theo rubric" còn là biên giới (Agent-as-a-Judge, paper-stage) — nên ta tự làm tầng đó, không chờ ai.

存在的原因： Agent 修改 UI 后自行声称无偏差，存在系统性故障
ui-pass-without-full-visual-review
。截图产出后无人打开查看，就等于未经测试。本工作流用三个相互独立的检查层取代“Agent 自己看后自己判定通过”，其中两层由机器执行。
13/07/26 决策（来自 /last30days）： 行业只有一个东西真正成熟并适用于 AI 生成 UI： baseline snapshot + pixel diff（
argos-ci/argos
：“检测非预期视觉变更”； Playwright
toHaveScreenshot
）。“LLM-judge 按 rubric 评 screenshot”这一层仍处于前沿（Agent-as-a-Judge，论文阶段）——因此我们要自行实现该层，不等待其他人。

WHAT

Purpose và context

目的与上下文

Purpose: thay "agent tự nhìn rồi tự cho pass" bằng ba tầng kiểm độc lập cho SPA local — baseline pixel-diff (máy), bất biến design/a11y (máy), đọc hết ảnh theo rubric (agent) — và chỉ pass khi máy VÀ mắt cùng sạch, có file ảnh làm bằng chứng.
Trigger (when to use):
- Vừa đổi theme / UI / rebrand và cần biết có làm hỏng gì ngoài ý muốn không.
- Frame có
```
ui_role≠none
```
  cần gate acceptance (xem skill
```
br
```
  § Vòng tự-kiểm thị giác).
- Extension browser không chụp được localhost (thường gặp) → headless CLI thay thế.
- User nói "qa thị giác", "visual qa", "route-shots", "screenshot từng route", "kiểm giao diện", "baseline diff", "UI có regression không", "test giao diện headless", "/visual-qa".
Non-goals: không dẫm
```
computer-use
```
(desktop AX / Orca browser); không phải verdict senior 4-mục (đó là
```
/qc-uiux
```
, dùng engine này); không nới ngưỡng để "hết lỗi".

目的： 用三层独立检查替代“Agent 自己看后自己判定通过”，面向本地 SPA——baseline pixel-diff（机器）、design/a11y 不变量（机器）、按 rubric 读完全部图像（Agent）——且仅当机器与视觉审阅都干净、存在图像文件作为证据时才通过。
触发条件（何时使用）：
- 刚修改 theme / UI / rebrand，需要知道是否造成了非预期破坏。
- Frame 的
```
ui_role≠none
```
  需要设置 acceptance gate（参见 skill
```
br
```
  § 视觉自检循环）。
- 浏览器扩展无法截取 localhost（常见）→ 使用 headless CLI 替代。
- User 表示“视觉 QA”“visual qa”“route-shots”“逐 route 截图”“检查界面”“baseline diff”“UI 是否有 regression”“headless 界面测试”“/visual-qa”。
Non-goals： 不涉及
```
computer-use
```
（desktop AX / Orca browser）；不是四项 senior verdict（那属于
```
/qc-uiux
```
，使用本引擎）；不放宽阈值来达到“没有错误”。

Mental model

心智模型

app chạy + route list THẬT + login → route-shots (ảnh + MANIFEST, mọi theme/state) → tầng 1 baseline diff (ngưỡng 0) → tầng 2 bất biến in-page (contrast-aa · monochrome-surface · rogue-slab · shadow-clipped · overlap · row-misalign) → tầng 3 đọc đủ N ảnh theo rubric → FINDINGS.md → sửa → chụp lại + đọc lại

app 运行 + 真实 route 列表 + 登录 → route-shots（图像 + MANIFEST、所有 theme/state）→ 第 1 层 baseline diff（阈值 0）→ 第 2 层页内不变量（contrast-aa · monochrome-surface · rogue-slab · shadow-clipped · overlap · row-misalign）→ 第 3 层按 rubric 读完全部 N 张图 → FINDINGS.md → 修复 → 重新截图 + 重新审阅

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	app đang chạy ( `--base` )	có	SPA localhost
In	route list từ router THẬT + tài khoản login	có	không đoán; login fail thì gate phải chết
In	danh sách theme/state từ chính app	có	không hardcode `light,dark` khi app có nhiều hơn
In	thư mục baseline	không	lần đầu tự tạo
Out	`<out>/*.png` + `MANIFEST.json`	có	không có file = CHƯA TỪNG CHỤP
Out	exit code với `--assert`	có cho gate	1 khi route lỗi / thiếu ảnh / vi phạm bất biến / lệch baseline
Out	`FINDINGS.md`	có	một dòng cho MỖI route, kể cả "sạch"

	字段	必填？	含义
In	app 正在运行（ `--base` ）	是	本地 SPA
In	真实 router 提供的 route 列表 + 登录账号	是	不猜测；登录失败时 gate 必须终止
In	app 自身提供的 theme/state 列表	是	app 有更多主题时，不得硬编码 `light,dark`
In	baseline 目录	否	首次运行时自动创建
Out	`<out>/*.png` + `MANIFEST.json`	是	没有文件 = 从未截图
Out	带 `--assert` 的 exit code	gate 必需	route 错误 / 缺图 / 违反不变量 / 偏离 baseline 时为 1
Out	`FINDINGS.md`	是	每个 route 一行，包括“干净”

Rules và capabilities

规则与能力

Luật rút từ máu — đừng lặp lại:

RULE-01 (MUST): THỨ GÌ TÍNH ĐƯỢC thì PHẢI để MÁY tính — cấm giao cho mắt. Tương phản chữ là con số (WCAG ratio = f(màu chữ, màu nền)). Rubric ghi "chữ đạt AA" mà không cài bất biến ⇒ evaluator MÙ: chữ mờ lọt qua cả trang đăng nhập, agent nhìn ảnh cũng không hình dung nổi. Tiêu chí nào định lượng được → phải thành assert, không phải thành dòng chữ trong rubric.
RULE-02 (MUST): KHÔNG ROUTE NÀO ĐƯỢC LÀ VÙNG MÙ. Driver login-trước ⇒
```
/auth
```
redirect ⇒ trang sign-in không bao giờ được audit — đúng trang có lỗi. Phải chụp trạng thái CHƯA đăng nhập trước, rồi mới login. Rà lại: còn state nào (modal, error, empty, loading) chưa từng vào khung hình?
RULE-03 (MUST): THEME LÀ MỘT TRẠNG THÁI — chụp ĐỦ light VÀ dark. App thường bật dark bằng class (
```
.dark
```
trên
```
<html>
```
) theo setting app, KHÔNG theo
```
prefers-color-scheme
```
⇒ headless mặc định chỉ bao giờ thấy light, còn dark là vùng mù tuyệt đối: user mở app ở dark thấy UI vỡ mà gate vẫn xanh. Bật
```
--themes light,dark
```
(mặc định) → lần đầu chạy lòi ra 172 chỗ trượt AAA ở dark trong khi light sạch bong. Hệ quả thiết kế: accent phải LẬT theo theme (mặt sáng → accent tối; mặt tối → accent sáng); một hằng số accent cho cả 2 theme là sai từ định nghĩa. Và cấm hardcode màu chữ trên accent (
```
color:#fff
```
) — ở theme kia thành trắng-trên-trắng 1.13:1.
RULE-04 (MUST): PHỦ MỌI THEME APP CUNG CẤP — danh sách lấy từ APP, không tự nghĩ. Tôi hardcode
```
light,dark
```
trong khi app có ba theme (
```
default
```
/
```
default-dark
```
/
```
paper
```
) ⇒
```
paper
```
không ai đụng ⇒ nó vỡ y hệt dark, user tìm ra chứ không phải gate. Luật: trước khi chạy, đọc danh sách theme từ chính app (dropdown Settings→Preferences / source
```
THEME_OPTIONS
```
) rồi phủ hết. Suy rộng: mọi TRỤC trạng thái (theme, locale, role, empty/full data) phải lấy từ app, không lấy từ trí nhớ của agent.
RULE-05 (MUST): ĐỔI TRẠNG THÁI PHẢI ĐI ĐÚNG ĐƯỜNG APP ĐỔI — rồi VERIFY nó đã đổi thật. Sai 2 tầng liên tiếp: ① gắn class
```
.dark
```
bằng tay (app dùng
```
data-theme
```
+ inject CSS ⇒ cơ chế KHÔNG TỒN TẠI); ② set
```
localStorage
```
(app GHI ĐÈ lại từ setting tài khoản trên server). Cả 2 lần gate XANH trên trạng thái không có thật — tệ hơn đỏ. Đường chắc chắn đúng là đường người dùng bấm (Settings → Preferences → chọn). Và luôn có bất biến: hai theme khác nhau mà nền y hệt ⇒ ảnh GIẢ ⇒ ASSERT FAIL (gate đang chụp cùng một theme hai lần rồi tự khen).
RULE-06 (MUST): THEME LÀ CƠ CHẾ CỦA APP, ĐỌC SOURCE TRƯỚC. Đừng giả định
```
.dark
```
/
```
prefers-color-scheme
```
. Grep
```
documentElement.classList
```
/
```
data-theme
```
/
```
localStorage
```
/ inject
```
<style>
```
để biết app đổi theme bằng gì; theme thường nạp bằng CSS inject lúc chạy ⇒ nó THẮNG file theme tĩnh của mình ở token thường, nhưng THUA rule
```
!important
```
⇒ ra giao diện nửa nạc nửa mỡ (nền theme-app + card theme-mình = mảng màu lạ giữa trang). Sửa đúng: viết bảng màu của mình vào chính file theme mà app inject, không viết block
```
.dark{}
```
ở nơi app không bao giờ đọc.
RULE-07 (MUST): LOGIN HỎNG = GATE PHẢI CHẾT. Login fail ⇒ mọi route redirect
```
/auth
```
⇒ driver audit 8 bản sao trang sign-in rồi in "design-ok". Xanh kiểu đó tệ hơn đỏ: nó xác nhận một app mà nó chưa từng nhìn thấy.
```
--assert
```
fail ngay khi login fail.
RULE-08 (MUST): USER BÁO LỖI + MÁY BÁO SẠCH ⇒ MÁY SAI, KHÔNG PHẢI USER SAI. (bài học 14/07/26 — user: "đây là developing không phải toà án mà bảo vệ luận điểm của mình khăng khăng như vậy".) Gate xanh KHÔNG phải lá chắn: nó chỉ chứng minh cái nó được dạy, trên state nó chụp được. User thấy lỗi = tồn tại một state/theme/bundle mà gate chưa từng vào. Cấm phản biện user bằng suy đoán ("chắc do cache", "chắc bấm nhầm phím") — mỗi lần đoán là đẩy việc kiểm chứng sang cho user, và tôi đã sai 3 lần liên tiếp kiểu đó. Đúng quy trình: (1) tin báo cáo, (2) tái hiện ĐÚNG state của user (route + theme + bundle + trạng thái đăng nhập/focus), (3) chỉ nói khi đã ĐO. Không tái hiện được thì nói thẳng "chưa tái hiện được", đừng dựng giả thuyết rồi bảo vệ nó.
RULE-09 (MUST): KHỬ NGẪU NHIÊN TRƯỚC KHI CHỤP, ĐỪNG NỚI NGƯỠNG. Con trỏ nhấp nháy + animation làm mọi route lệch baseline ~0.04% mỗi lần chụp ⇒ gate đỏ vĩnh viễn ⇒ bị phớt lờ ⇒ regression thật lọt qua. Driver tiêm CSS
```
animation/transition:none; caret-color:transparent
```
+ ẩn con trỏ CodeMirror ngay lúc init ⇒ diff về 0%. Nới
```
--diff-threshold
```
để "hết kêu" là làm mù máy, không phải sửa lỗi.
RULE-10 (MUST): SELECTOR THAM LAM = TỰ BẮN VÀO CHÂN.
```
[class*="cursor"]
```
trong CSS khử-nhiễu trúng luôn
```
cursor-pointer
```
/
```
cursor-text
```
của Tailwind ⇒ ẩn mất ô nhập ⇒ login chết ⇒ gate tự làm hỏng app nó đang kiểm. Mọi CSS/selector do gate tiêm vào phải hẹp nhất có thể và phải chạy thử full-flow (login → mọi route) sau khi thêm.
RULE-11 (MUST): GATE PHẢI CHẠY ĐƯỢC TỪ REPO SẠCH. Thiếu
```
playwright-core
```
⇒
```
node route-shots.mjs
```
chết ngay dòng import ⇒ acceptance_test của frame UI không bao giờ chạy = gate chết mà không ai biết. Deps khai trong
```
skills/visual-qa/assets/package.json
```
; cài:
```
npm i --prefix skills/visual-qa/assets
```
.
RULE-12 (MUST): BẰNG CHỨNG > LỜI. Pass/fixed chỉ hợp lệ khi có FILE ẢNH. Không file = chưa làm. Cấm khai pass bằng suy luận.
RULE-13 (MUST): ĐỌC HẾT, không chọn lọc. Đọc 3/7 ảnh rồi kết luận là nguyên nhân gốc của failure
```
ui-pass-without-full-visual-review
```
— lỗi nằm sẵn trong ảnh chưa mở.
RULE-14 (MUST): "Máy OK" ≠ "UI đẹp". Bất biến chỉ biết những gì nó được dạy. Gate xanh KHÔNG phải cớ để bỏ bước đọc ảnh.
RULE-15 (MUST): NGƯỠNG là con dao hai lưỡi. Ngưỡng lỏng → lọt lỗi thật (0.5% diff bỏ lọt một regression làm phẳng toàn bộ card). Ngưỡng chặt quá → kêu oan → gate noisy = gate CHẾT. Baseline dùng ngưỡng 0 + duyệt tay; bất biến DOM phải có ngưỡng phân biệt lỗi thật với nhiễu.
RULE-16 (MUST): CSS thì ĐO, đừng ĐOÁN. Chẩn đoán bằng mắt sai 4 lần liên tiếp (clip → collision → sai selector → sai specificity). Chỉ khi query
```
getComputedStyle
```
mới ra gốc. Trước mọi fix CSS: đo computed style + đo rect, rồi mới sửa. Sau khi sửa: đo lại trước khi nhìn ảnh.
RULE-17 (MUST): Đừng làm MÙ máy để "hết lỗi". Hạ blur xuống dưới ngưỡng detector = che lỗi, không sửa lỗi (aura vẫn bị crop). Sửa defect, đừng sửa thước đo.
RULE-18 (MUST): Trong container
overflow:hidden
(rail hẹp, tab bar): KHÔNG dùng bóng outset. Nó sẽ bị cắt hoặc đổ vào khe → vệt xấu. Dùng inset (không thể tràn) hoặc bỏ bóng.
```
overflow-x:visible
```
KHÔNG khả thi khi trục kia là
```
auto
```
(CSS ép về auto).
RULE-19 (MUST): playwright-core + Chrome hệ thống (không tải chromium 130MB). Baseline diff cần
```
pixelmatch
```
+
```
pngjs
```
(nhỏ, không có thì tự bỏ qua baseline).
RULE-20 (MUST): networkidle
cấm với SPA realtime — dùng
```
domcontentloaded
```
+ chờ cố định.
RULE-21 (MUST): Không dẫm
computer-use
(desktop AX / Orca browser). Skill này là headless CLI cho SPA localhost.
Capabilities: chạy trình duyệt headless trên localhost; đo computed style + rect in-page; so pixel với baseline; ghi ảnh/manifest/findings; sửa UI dự án đích.

从实战中提炼的规则——不要重复：

RULE-01 (MUST)：凡是能够计算的，都必须让机器计算——绝不能交给肉眼。 文字对比度是一个数值（WCAG ratio = f(文字颜色、背景颜色)）。如果 rubric 写着“文字达到 AA”，却未配置相应不变量 ⇒ evaluator 是盲的：模糊文字能一路通过整个登录页，Agent 看图时也无法想象出来。任何可量化的标准 → 必须写成 assert，而不是 rubric 中的一行文字。
RULE-02 (MUST)：不允许任何 route 成为盲区。 Driver 先登录 ⇒
```
/auth
```
重定向 ⇒ 登录页永远不会被审计——而这恰恰是存在问题的页面。必须先捕获尚未登录的状态，再登录。再检查：是否还有任何状态（modal、error、empty、loading）从未进入过画面？
RULE-03 (MUST)：THEME 是一种状态——light 和 dark 都必须完整捕获。 App 通常根据 app 自身的 setting，通过 class（
```
<html>
```
上的
```
.dark
```
）启用 dark，而不是根据
```
prefers-color-scheme
```
⇒ headless 默认几乎永远只能看到 light，而 dark 是彻底的盲区：User 在 dark 下打开 app 会看到 UI 崩坏，gate 却仍然显示绿色。启用
```
--themes light,dark
```
（默认值）→ 首次运行便暴露出 172 处未达到 AAA 的 dark 问题，而 light 完全干净。由此得出的设计结论是：accent 必须随 theme 翻转（明亮表面 → 深色 accent；深色表面 → 浅色 accent）；对两个 theme 使用同一个固定 accent，从定义上就是错误的。并且禁止在 accent 上硬编码文字颜色（
```
color:#fff
```
）——在另一个 theme 中会变成白底白字，对比度仅 1.13:1。
RULE-04 (MUST)：覆盖 app 提供的所有 THEME——列表取自 APP，不能自行臆测。 我曾硬编码
```
light,dark
```
，但 app 实际有三个 theme（
```
default
```
/
```
default-dark
```
/
```
paper
```
）⇒
```
paper
```
根本无人触碰 ⇒ 它像 dark 一样崩坏，最后是 User 发现，而不是 gate。规则：运行前，从 app 自身读取 theme 列表（Settings→Preferences 下拉菜单 / 源码中的
```
THEME_OPTIONS
```
），然后全部覆盖。推广而言：所有状态轴（theme、locale、role、empty/full data）都必须取自 app，不能依赖 Agent 的记忆。
RULE-05 (MUST)：切换状态必须走 app 自己的切换路径——然后 VERIFY 它确实已改变。 曾连续犯两类错误：① 手动挂载
```
.dark
```
class（app 使用
```
data-theme
```
+ inject CSS ⇒ 该机制根本不存在）；② 设置
```
localStorage
```
（app 会根据服务器上的账号 setting 再次覆盖它）。两次 gate 都在一个并不存在的状态上显示绿色——这比红色更糟。可靠路径是User 实际点击的路径（Settings → Preferences → 选择）。并且始终需要以下不变量：两个不同 theme 如果背景完全相同 ⇒ 图像是假的 ⇒ ASSERT FAIL（gate 实际上把同一个 theme 截了两次，然后自行称赞自己）。
RULE-06 (MUST)：THEME 是 APP 的机制，必须先读 SOURCE。 不要臆测
```
.dark
```
/
```
prefers-color-scheme
```
。Grep
```
documentElement.classList
```
/
```
data-theme
```
/
```
localStorage
```
/ inject
```
<style>
```
，以确定 app 使用什么机制切换 theme；theme 通常通过运行时 CSS inject 加载 ⇒ 它在普通 token 上会胜过我们的静态 theme 文件，却会败给
```
!important
```
rule ⇒ 最终得到一个半新半旧的界面（背景来自 app theme + card 来自我们的 theme = 页面中间出现奇怪的色块）。正确修复：把我们的调色板写入 app 实际 inject 的那个 theme 文件本身，而不是在 app 从不读取的位置写
```
.dark{}
```
。
RULE-07 (MUST)：LOGIN 失败 = GATE 必须终止。 Login 失败 ⇒ 所有 route 都重定向到
```
/auth
```
⇒ driver 审计 8 份相同的登录页副本，然后打印“design-ok”。这种绿色比红色更糟：它确认的是一个自己从未真正看过的 app。
```
--assert
```
必须在 login 失败时立即失败。
RULE-08 (MUST)：USER 报告错误 + 机器报告干净 ⇒ 机器错了，不是 USER 错了。（经验总结于 14/07/26——User：“这是在开发，不是法庭，别顽固地捍卫自己的观点。”）Gate 显示绿色并不是护身符：它只能证明它被教会的那些内容，以及它能捕获到的状态。User 看见错误，说明存在某个 gate 从未进入过的 state/theme/bundle。禁止用推测反驳 User（“肯定是 cache”“肯定是你按错键了”）——每次猜测都等于把验证工作推给 User，而我曾连续三次这样犯错。正确流程是：（1）相信报告；（2）精确复现 User 的 state（route + theme + bundle + 登录/focus 状态）；（3）只有实际测量后才能下结论。无法复现时，就直接说“尚未复现”，不要编造假设再为之辩护。
RULE-09 (MUST)：截图前先消除随机性，不要放宽阈值。 光标闪烁 + animation 会让每个 route 每次截图都偏离 baseline 约 0.04% ⇒ gate 永远显示红色 ⇒ 最终被忽视 ⇒ 真正的 regression 反而漏过。Driver 在 init 时注入 CSS
```
animation/transition:none; caret-color:transparent
```
，并立即隐藏 CodeMirror 光标 ⇒ diff 回到 0%。放宽
```
--diff-threshold
```
让它闭嘴，等于蒙蔽机器，不是修复错误。
RULE-10 (MUST)：宽泛的选择器等于自伤。 CSS 中的
```
[class*="cursor"]
```
在去噪时也会命中 Tailwind 的
```
cursor-pointer
```
/
```
cursor-text
```
⇒ 输入框被隐藏 ⇒ login 失败 ⇒ gate 亲手弄坏了正在测试的 app。Gate 注入的所有 CSS/selector 都必须尽可能狭窄，并且添加后必须跑通完整流程（login → 所有 route）。
RULE-11 (MUST)：GATE 必须能在干净的 repo 中运行。 缺少
```
playwright-core
```
⇒
```
node route-shots.mjs
```
会在 import 行立即崩溃 ⇒ frame UI 的 acceptance_test 永远无法运行 = gate 死了却无人知晓。依赖项声明在
```
skills/visual-qa/assets/package.json
```
；安装命令：
```
npm i --prefix skills/visual-qa/assets
```
。
RULE-12 (MUST)：证据 > 言语。 只有存在图像 FILE，Pass/fixed 才是有效的。没有文件就代表尚未完成。禁止通过推断来宣称通过。
RULE-13 (MUST)：全部读完，不能挑选。 只读取 7 张图中的 3 张便断言 failure
```
ui-pass-without-full-visual-review
```
的根因——错误就藏在尚未打开的图像里。
RULE-14 (MUST)：“机器 OK” ≠ “UI 漂亮”。 不变量只知道它被教会的那些内容。Gate 显示绿色并不能成为跳过阅读图像步骤的理由。
RULE-15 (MUST)：阈值是一把双刃剑。 阈值过松 → 漏掉真实错误（0.5% diff 可以放过一个把整排 card 都压平的 regression）。阈值过严 → 误报 ⇒ gate noisy = gate 已死。Baseline 使用阈值 0 + 人工审阅；DOM 不变量必须设置能够区分真实错误与噪声的阈值。
RULE-16 (MUST)：CSS 要测量，不要猜。 仅凭肉眼诊断曾连续错 4 次（clip → collision → selector 错误 → specificity 错误）。只有 query
```
getComputedStyle
```
才能找到根因。每次修复 CSS 之前：测量 computed style + 测量 rect，然后再修改。修复之后：先重新测量，再看图像。
RULE-17 (MUST)：不要为了“没有错误”而蒙蔽机器。 将 blur 降到 detector 阈值以下，只是遮盖错误，并未修复错误（aura 仍会被 crop）。修复 defect，不要修改测量标准。
RULE-18 (MUST)：在
```
overflow:hidden
```
的容器（狭窄 rail、tab bar）中：不要使用 outset 阴影。 它会被裁切或溢出到缝隙中，形成难看的痕迹。使用 inset（无法向外溢出），或者干脆去掉阴影。当另一轴为
```
auto
```
时，
```
overflow-x:visible
```
不可行（CSS 会强制其变为 auto）。
RULE-19 (MUST)：使用 playwright-core + 系统 Chrome（不要下载 130MB 的 chromium）。Baseline diff 需要
```
pixelmatch
```
+
```
pngjs
```
（体积很小；没有时跳过 baseline）。
RULE-20 (MUST)：实时 SPA 禁止使用
networkidle
——改用
```
domcontentloaded
```
+ 固定等待。
RULE-21 (MUST)：不要涉及
computer-use
（desktop AX / Orca browser）。本 Skill 是面向 localhost SPA 的 headless CLI。
Capabilities：在 localhost 上运行 headless 浏览器；测量 computed style + 页内 rect；与 baseline 进行 pixel 对比；写入图像/manifest/findings；修复目标项目的 UI。

Failure boundaries

Login fail →
```
--assert
```
failed ngay, không audit bản sao trang sign-in.
Thiếu
```
playwright-core
```
→ gate chết từ dòng import: blocked, cài
```
npm i --prefix skills/visual-qa/assets
```
.
Lệch baseline ≠ 0 → failed tới khi người xem + duyệt bằng
```
--update-baseline
```
.
User báo lỗi mà máy báo sạch → máy sai: tái hiện đúng state; chưa tái hiện được thì nói thẳng "chưa tái hiện được".
Máy sạch nhưng chưa đọc đủ N ảnh → chưa xong.

Login 失败 →
```
--assert
```
立即 failed，不得审计登录页副本。
缺少
```
playwright-core
```
→ gate 在 import 行崩溃：状态为 blocked，执行
```
npm i --prefix skills/visual-qa/assets
```
安装。
偏离 baseline ≠ 0 → 状态为 failed，直到查看者审阅并使用
```
--update-baseline
```
批准。
User 报告错误但机器报告干净 → 机器错了：精确复现对应 state；无法复现时直接说明“尚未复现”。
机器报告干净，但尚未读完全部 N 张图 → 尚未完成。

HOW

Main workflow

W01–W07 ứng với bước 0–6 bên dưới.

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	app, router, tài khoản	Xác nhận app chạy, lấy route list THẬT + theme list từ app	route + theme list	app không chạy → blocked
W02	effect	route list	Chụp bằng `route-shots.mjs` (+ `--assert` )	ảnh + `MANIFEST.json`	login fail → failed
W03	deterministic	ảnh + baseline	Baseline diff ngưỡng 0	diff	≠ 0 → xem + duyệt (B02) hoặc sửa
W04	deterministic	trang in-page	Bất biến máy-kiểm	vi phạm hoặc sạch	FAIL cứng → W06
W05	judgment	MANIFEST N route	`Read` đủ N ảnh, chấm theo rubric	dòng cho mỗi route	thiếu ảnh chưa đọc → chưa xong
W06	effect	findings	`FINDINGS.md` (nguyên nhân GỐC) → sửa	code đã sửa	—
W07	deterministic	code đã sửa	Chụp lại → đọc lại	máy sạch VÀ mắt sạch	còn lỗi → W06

Chi tiết từng bước (nguồn chân lý cho W01–W07):

0. App phải đang chạy. Biết route list (lấy từ router THẬT, không đoán) + tài khoản login.

1. CHỤP + BẰNG CHỨNG.

bash

node skills/visual-qa/assets/route-shots.mjs \
  --base http://localhost:5230 --out <dir>/qa-shots \
  --baseline <dir>/qa-baseline \
  --user demo --pass demo --assert

Sinh

<out>/*.png

+ MANIFEST.json
(route → file → bytes). Không có file = CHƯA TỪNG CHỤP.

2. BASELINE DIFF (máy tầng 1) — bắt thay đổi NGOÀI Ý MUỐN. Lần đầu tự tạo baseline. Lần sau so pixel-by-pixel. Ngưỡng mặc định = 0: mọi diff ≠ 0 đều FAIL và phải được xem + duyệt tay bằng

--update-baseline

. Đây là tầng duy nhất bắt được loại lỗi mà bất-biến-CSS và mắt agent đều MÙ (vd: sửa quá tay làm phẳng cả UI).

3. BẤT BIẾN MÁY-KIỂM (máy tầng 2) — design conformance + a11y. Chạy in-page bằng computed style:

```
contrast-aa
```
— WCAG AAA cho MỌI text node (tính tỉ lệ tương phản từ màu chữ + nền hiệu dụng; 7:1 thường, 4.5:1 chữ lớn). FAIL cứng.
```
monochrome-surface
```
— pane lớn (sidebar/aside/nav) phải cùng màu nền. FAIL cứng.
```
rogue-slab
```
— MỌI phần tử ≥2% viewport có nền đục lệch nền body > 1.6:1. FAIL cứng. (
```
monochrome-surface
```
chỉ soi sidebar/aside/nav ⇒ mù với mảng màu lạ là
```
<div>
```
bất kỳ giữa trang.)
```
shadow-clipped
```
— aura outset trong cha
```
overflow:hidden
```
(có ngưỡng blur). Cảnh báo.
```
overlap
```
— hai control (
```
button/a/input/[role=button]
```
) KHÔNG phải cha-con mà rect chồng ≥4px cả hai chiều. Bắt lỗi nút đè lên nhau (vd
```
position:fixed
```
với magic-offset lúc badge rộng biến thiên). FAIL cứng.
```
row-misalign
```
— control cùng cha, gần cùng hàng (top lệch ≤6px) mà chiều cao lệch >3px. Bắt lỗi nút cạnh nhau không bằng chiều cao (vd nút toggle cao hơn badge do padding/font khác). FAIL cứng. (Hai rule này thêm 15/07/26 vì cả
```
/redesign-existing-projects
```
[đọc CSS TĨNH — không đo được rect] lẫn unit-test [kiểm NỘI DUNG, không kiểm toạ độ] đều mù với lỗi hình học lúc render. Ngưỡng overlap CỐ Ý không dùng %-diện-tích: bug thật chỉ clip mép nút = 18% dt, mọi ngưỡng % đều lọt — 2 control độc lập chồng ≥ vài px đã là lỗi.)

Mở rộng bất biến theo design spec của dự án.

4. ĐỌC ẢNH — COVERAGE CỨNG + RUBRIC (tầng người/agent). MANIFEST có N route → PHẢI
Read
đủ N ảnh. FINDINGS phải có một dòng cho MỖI route (kể cả "sạch"). Chấm theo rubric, không cảm tính — vd neumorphism: ① mặt đơn sắc ② bóng không bị cắt ③ CTA phẳng accent ④ chữ/icon AA ⑤ empty-state đúng brand ⑥ focus ring.

5. FINDINGS.md → SỬA. Bảng

# · route · vấn đề · mức · **nguyên nhân GỐC** · cách sửa

6. CHỤP LẠI → ĐỌC LẠI → mới pass. Máy sạch VÀ mắt sạch. Thiếu một trong hai = chưa xong.

W01–W07 对应下方步骤 0–6。

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	app、router、账号	确认 app 正在运行，从 app 获取真实 route 列表 + theme 列表	route + theme 列表	app 未运行 → blocked
W02	effect	route 列表	使用 `route-shots.mjs` 截图（+ `--assert` ）	图像 + `MANIFEST.json`	login 失败 → failed
W03	deterministic	图像 + baseline	阈值为 0 的 baseline diff	diff	≠ 0 → 查看并批准（B02），或修复
W04	deterministic	页内内容	机器检查不变量	违规或干净	硬 FAIL → W06
W05	judgment	包含 N 个 route 的 MANIFEST	`Read` 全部 N 张图，按 rubric 评分	每个 route 一行	有图像未读 → 尚未完成
W06	effect	findings	`FINDINGS.md` （根因）→ 修复	已修复代码	—
W07	deterministic	已修复代码	重新截图 → 重新审阅	机器干净且视觉审阅干净	仍有问题 → W06

各步骤详情（W01–W07 的事实来源）：

0. App 必须正在运行。 已知 route 列表（取自真实 router，不猜测）+ 登录账号。

1. 截图 + 证据。

bash

node skills/visual-qa/assets/route-shots.mjs \
  --base http://localhost:5230 --out <dir>/qa-shots \
  --baseline <dir>/qa-baseline \
  --user demo --pass demo --assert

生成

<out>/*.png

+ MANIFEST.json
（route → 文件 → 字节数）。没有文件 = 从未截图。

2. BASELINE DIFF（机器第 1 层）——捕获非预期变更。 首次运行时自动创建 baseline。后续运行逐像素比较。默认阈值 = 0：任何 diff ≠ 0 都会 FAIL，并且必须查看图像，再使用

--update-baseline

人工批准。这是唯一能够捕获以下错误类型的层： CSS 不变量和 Agent 的肉眼都看不到它，例如修复过度而把整个 UI 压平。

3. 机器检查不变量（机器第 2 层）——design conformance + a11y。 使用 computed style 在页内运行：

```
contrast-aa
```
— 对所有 text node 执行 WCAG AAA（根据文字颜色 + 有效背景色计算对比度；通常为 7:1，大号文字为 4.5:1）。硬 FAIL。
```
monochrome-surface
```
— 大型 pane（sidebar/aside/nav）必须使用相同背景色。硬 FAIL。
```
rogue-slab
```
— 所有占 viewport ≥2% 且背景色与 body 背景偏差 >1.6:1 的元素。硬 FAIL。 （
```
monochrome-surface
```
只检查 sidebar/aside/nav ⇒ 无法发现页面中间任意
```
<div>
```
形成的异常色块。）
```
shadow-clipped
```
— 父元素为
```
overflow:hidden
```
时出现带 blur 阈值的 outset aura。警告。
```
overlap
```
— 两个 control（
```
button/a/input/[role=button]
```
）不存在父子关系，且 rect 在两个方向上均重叠 ≥4px。用于捕获按钮互相叠压的问题（例如
```
position:fixed
```
搭配 magic-offset，badge 变宽后发生偏移）。硬 FAIL。
```
row-misalign
```
— control 具有相同父元素、处于近似同一行（top 差异 ≤6px），但高度差异 >3px。用于捕获相邻按钮高度不一致的问题（例如 toggle 因 padding/font 不同而高于 badge）。硬 FAIL。 （这两条规则添加于 15/07/26，因为
```
/redesign-existing-projects
```
[只读静态 CSS——无法测量 rect]与 unit-test[检查内容，不检查坐标]都看不到渲染时的几何错误。overlap 阈值有意不使用面积百分比：真实 bug 可能只裁掉按钮边缘 = 18% 面积，所有百分比阈值都会漏掉——两个独立 control 重叠 ≥ 几 px 就已经是错误。）

根据项目的 design spec 扩展不变量。

4. 阅读图像——硬性 COVERAGE + RUBRIC（人/Agent 层）。 MANIFEST 中有 N 个 route → 必须
Read
全部 N 张图。FINDINGS 必须为每个 route 写一行 （包括“干净”）。按 rubric 评分，不能凭印象——例如 neumorphism：① 单色平面 ② 阴影未被裁切 ③ CTA 使用平面 accent ④ 文字/icon 达到 AA ⑤ empty-state 符合 brand ⑥ focus ring。

5. FINDINGS.md → 修复。 表格格式为

# · route · 问题 · 严重程度 · **根因** · 修复方式

。

6. 重新截图 → 重新审阅 → 才能通过。 机器干净且视觉审阅干净。缺少其中任何一个都代表尚未完成。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	frame gate chỉ cần 1 route	chạy `--route <r>`	—	W03
B02	user_optional	lệch baseline là thay đổi CỐ Ý đã xem	`--update-baseline`	chưa xem ảnh → không được duyệt	W04
B03	capability_optional	có `pixelmatch` + `pngjs`	chạy baseline diff	không có → tự bỏ qua baseline	W04
B04	recovery	user báo lỗi mà gate xanh	tái hiện ĐÚNG state (route + theme + bundle + đăng nhập/focus), đo rồi mới nói	không tái hiện được → nói thẳng	W02

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	conditional_required	frame gate 只需要 1 个 route	运行 `--route <r>`	—	W03
B02	user_optional	baseline 偏差属于已查看的预期变更	`--update-baseline`	尚未查看图像 → 不得批准	W04
B03	capability_optional	存在 `pixelmatch` + `pngjs`	执行 baseline diff	不存在 → 跳过 baseline	W04
B04	recovery	User 报告错误但 gate 显示绿色	精确复现对应 state（route + theme + bundle + 登录/focus），完成测量后再下结论	无法复现 → 直接说明	W02

Validation và stopping

Validation 与停止条件

Máy: exit code

--assert

(route lỗi / thiếu ảnh / bất biến / baseline). Mắt: FINDINGS có đủ một dòng cho mỗi route trong MANIFEST. Pass chỉ khi cả hai sạch VÀ có file ảnh; không có file = chưa làm.

机器：

--assert

的 exit code（route 错误 / 缺图 / 违反不变量 / baseline 偏差）。视觉审阅：FINDINGS 中为 MANIFEST 的每个 route 提供一行。只有两者都干净且存在图像文件时才算通过；没有文件 = 尚未完成。

Examples

Positive: đổi theme app
```
/br
```
sinh, 7 route × 3 theme từ
```
THEME_OPTIONS
```
→
```
route-shots.mjs --assert
```
exit 0, baseline diff 0%, agent
```
Read
```
đủ ảnh, FINDINGS 7 dòng "sạch" → pass kèm ảnh.
Boundary/failure: light sạch nhưng chưa phủ dark → bật
```
--themes light,dark
```
lòi ra 172 chỗ trượt AAA →
```
--assert
```
exit 1; sửa accent lật theo theme rồi chụp lại, không nới
```
--diff-threshold
```
.

Positive： 修改由
```
/br
```
生成的 app theme，7 route × 来自
```
THEME_OPTIONS
```
的 3 个 theme →
```
route-shots.mjs --assert
```
exit 0，baseline diff 0%，Agent
```
Read
```
全部图像，FINDINGS 包含 7 行“干净”→ 携带图像通过。
Boundary/failure： light 干净但尚未覆盖 dark → 启用
```
--themes light,dark
```
后暴露 172 处未达到 AAA 的问题 →
```
--assert
```
exit 1；让 accent 随 theme 翻转后重新截图，不得放宽
```
--diff-threshold
```
。

Reference — Cờ driver

Reference — Driver flags

--base

--out

--user

--pass

--route <r>

(1 route, cho frame gate) ·

--assert

(exit 1 khi: route lỗi / thiếu ảnh / vi phạm bất biến / lệch baseline) ·

--baseline <dir>

--update-baseline

(duyệt thay đổi cố ý) ·

--diff-threshold <%>

(mặc định 0).

--base

--out

--user

--pass

--route <r>

（1 个 route，用于 frame gate）·

--assert

（出现以下情况时 exit 1：route 错误 / 缺图 / 违反不变量 / 偏离 baseline）·

--baseline <dir>

--update-baseline

（批准预期变更）·

--diff-threshold <%>

（默认 0）。