Skill: visual-qa — workflow tự-kiểm thị giác (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.

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".

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

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"

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.

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.

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.

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

Validation và stopping

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.

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
```
.

Reference — Cờ driver

--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).

visual-qa

NPX Install

SKILL.md Content