qc-uiux

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: qc-uiux

WHAT

Purpose và context

目的与背景

Purpose: cho một verdict SENIOR về UI/UX của route/màn đang có — bốn mục (accessibility · visual-hierarchy · consistency · antipattern), mỗi mục điểm/10 + lỗi nặng nhất + cách sửa — với phần đo được lấy từ engine tất định, phần cần mắt do LLM audit.
Trigger (when to use):
- Vừa dựng/đổi UI (mockup
```
/br
```
  , trang mới, component) và muốn một cặp mắt senior soi trước khi chốt.
- Trước commit thay đổi UI đáng kể — cắm tùy chọn vào
```
/orca-workflow
```
  trước
```
verify-before-commit
```
  , và tự-động sau mỗi
```
/br run
```
  frame có UI.
- User nói "qc uiux", "audit ui", "soi giao diện", "dẹp antipattern ui", "/qc-uiux".
Non-goals: KHÔNG dùng cho: đổi mới thẩm mỹ tổng thể (đó là
```
/redesign-existing-projects
```
), hay chỉ chụp+so pixel (đó là
```
/visual-qa
```
— qc-uiux GỌI nó làm engine đo). Không review CODE (đó là
```
/qc-code
```
). Verdict không chặn commit.

Purpose： 为当前 route/页面的 UI/UX 提供 SENIOR verdict——分为四个板块（accessibility · visual-hierarchy · consistency · antipattern），每项给出评分/10 + 最严重问题 + 修复方法；可测量部分来自确定性 engine，需要肉眼判断的部分由 LLM audit 完成。
Trigger（何时使用）：
- 刚搭建或修改 UI（mockup
```
/br
```
  、新页面、component），希望在定稿前获得 senior 视角审查。
- 在 commit 重大 UI 改动之前——将可选 hook 接入
```
/orca-workflow
```
  ，置于
```
verify-before-commit
```
  之前；也可在每次
```
/br run
```
  生成包含 UI 的 frame 后自动运行。
- 用户说「qc uiux」、「audit ui」、「soi giao diện」（检查界面）、「dẹp antipattern ui」（清理 UI antipattern）、「/qc-uiux」。
Non-goals： 不用于以下场景：整体 aesthetics 更新（应使用
```
/redesign-existing-projects
```
），或仅进行截图和像素比较（应使用
```
/visual-qa
```
——qc-uiux 会将其作为测量 engine 调用）。不进行 CODE review（应使用
```
/qc-code
```
）。Verdict 不会阻止 commit。

Mental model

route/màn → engine tất định (DESIGN_AUDIT đo rect thật) = DỮ KIỆN → 4 mục × (điểm/10 · lỗi nặng nhất · cách sửa) = Ý KIẾN có dẫn số → verdict PASS | CẦN SỬA (theo mục/route yếu nhất) → sửa → engine lại (đỏ→xanh)

. Đắt (LLM, gọi tay) tách rẻ (engine, auto hook).

route/页面 → 确定性 engine（DESIGN_AUDIT 测量真实 rect）= 事实 → 4 个板块 ×（评分/10 · 最严重问题 · 修复方法）= 有数据支撑的意见 → verdict：PASS | 需要修复（依据最弱的板块/route）→ 修复 → 再次运行 engine（红→绿）

。昂贵部分（LLM，手动调用）与便宜部分（engine，自动 hook）相互分离。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	route/màn	không (mặc định = mockup/route hiện có)	user chỉ định thì soi cái đó
In	`<base-url>` chạy được	có cho phần đo	engine headless cần server; không dựng được → fail-open
In	loại route (list/table?)	tự xác định	có → nạp `references/list-control-checklist.md`
Out	4 mục × điểm/10 · lỗi nặng nhất · cách sửa	có	mục 3 kèm bảng drift; mục có lỗi đo được dẫn số engine
Out	verdict	có	`PASS` hoặc `CẦN SỬA` + danh sách phải sửa — ADVISORY
Out	draft `llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md` + index + log	có (trừ khi chỉ chạy engine)	mục Output Report

	字段	必填？	含义
In	route/页面	否（默认=当前 mockup/route）	用户指定时审查对应对象
In	可运行的 `<base-url>`	测量部分必填	headless engine 需要 server；无法启动时采用 fail-open
In	route 类型（list/table？）	自动确定	存在时加载 `references/list-control-checklist.md`
Out	4 个板块 × 评分/10 · 最严重问题 · 修复方法	是	板块 3 附带 drift 表；存在可测量错误的板块附带 engine 数值
Out	verdict	是	`PASS` 或 `需要修复` + 待修复列表——ADVISORY
Out	draft `llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md` + index + log	是（仅运行 engine 时除外）	见 Output Report 部分

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): Tách đắt/rẻ: LLM audit (4 mục) = gọi tay / bước workflow tùy chọn. Đo tất định = auto qua engine visual-qa. KHÔNG gọi LLM trong hook (nguyên tắc hook-0-token).
RULE-02 (MUST): Verdict advisory, engine đo gác cứng — không để LLM verdict chặn commit; số đo (contrast/tap-target/geometry) mới là dữ kiện.
RULE-03 (MUST): Đọc CSS là MÙ hình học — mọi nhận định layout/kích cỡ/contrast phải ĐO rect thật qua engine, không suy từ CSS tĩnh.
RULE-04 (MUST): Không dẫm:
```
/redesign-existing-projects
```
= đổi mới thẩm mỹ ·
```
/visual-qa
```
= chụp+gác pixel-diff ·
```
/qc-code
```
= review CODE.
```
/qc-uiux
```
= verdict senior 4-mục UI/UX + reuse engine đo.
RULE-05 (MUST): Chức năng trước thẩm mỹ, không bình quân điểm (học từ skill
```
qa
```
của browser-use, 09/2026): nếu route/luồng đang soi có tác vụ người dùng (submit, checkout, đăng nhập) mà tác vụ KHÔNG hoàn thành được → verdict
```
CẦN SỬA
```
bất kể 4 mục điểm cao — đẹp không cứu được luồng gãy. Verdict tổng lấy theo mục/route YẾU NHẤT, không lấy trung bình cộng.
RULE-06 (MUST): Ảnh chụp sạch không chứng minh gì — khi engine chạy headless, moi thêm lỗi ẩn: console
```
error
```
,
```
pageerror
```
, response
```
>= 400
```
,
```
requestfailed
```
(xem
```
/playwright-verify
```
Rules). Trang trông đẹp mà ném lỗi ở mọi cú bấm → ghi vào mục 4, không cho PASS.
RULE-07 (MUST): a11y là luật, không phải gu — carve-out CLAUDE.md: không lười ở contrast/tap-target/label. Chỉ ~30% WCAG tự-động → phần còn lại ghi rõ "cần mắt người / nợ
```
[[150726-unknown-ledger]]
```
".
Capabilities: chạy trang trong trình duyệt headless để đo DOM/rect/contrast (0-token); đọc CSS/DOM; ghi draft wiki. Không sửa UI trong lúc audit.

RULE-01（MUST）：分离昂贵与便宜部分： LLM audit（4 个板块）通过手动调用或可选 workflow 步骤执行。确定性测量通过 visual-qa engine 自动运行。Hook 中不得调用 LLM（hook-0-token 原则）。
RULE-02（MUST）：Verdict 为 advisory，engine 测量才是硬门禁——不得让 LLM verdict 阻止 commit；contrast、tap-target、geometry 等测量结果才是事实依据。
RULE-03（MUST）：读取 CSS 无法了解几何布局——所有关于 layout、尺寸和 contrast 的判断都必须通过 engine 测量真实 rect，不得根据静态 CSS 推断。
RULE-04（MUST）：不得重叠使用：
```
/redesign-existing-projects
```
= 整体 aesthetics 更新 ·
```
/visual-qa
```
= 截图+像素 diff ·
```
/qc-code
```
= CODE review。
```
/qc-uiux
```
= 四板块 UI/UX senior verdict + 复用测量 engine。
RULE-05（MUST）：功能优先于 aesthetics，不得平均计算分数（借鉴 browser-use 的
```
qa
```
skill，09/2026）：如果所审查的 route/流程包含用户任务（submit、checkout、登录），但任务无法完成，则无论四个板块得分多高，verdict 都必须为
```
需要修复
```
——界面再漂亮也无法弥补流程中断。总 verdict 取最弱板块/route 的结果，而不是取平均值。
RULE-06（MUST）：干净截图无法证明任何问题不存在——headless engine 运行时还要挖掘隐藏错误：console
```
error
```
、
```
pageerror
```
、response
```
>= 400
```
、
```
requestfailed
```
（参见
```
/playwright-verify
```
Rules）。如果页面看起来美观，但每次点击都抛出错误，则写入板块 4，不得判定为 PASS。
RULE-07（MUST）：a11y 是规则，不是偏好——遵循 CLAUDE.md 中的例外约定：不得在 contrast、tap-target、label 上放宽标准。只有约 30% 的 WCAG 条款可以自动检测；其余部分必须明确写为「需要人工肉眼检查/待办
```
[[150726-unknown-ledger]]
```
」。
Capabilities：在 headless 浏览器中运行页面并测量 DOM/rect/contrast（0-token）；读取 CSS/DOM；写入 draft wiki。Audit 期间不修改 UI。

Failure boundaries

Không dựng được server/headless → engine fail-open (không chặn); audit LLM vẫn chạy nhưng phải ghi phần đo được là chưa có số.
Tác vụ người dùng trên route không hoàn thành được → verdict
```
CẦN SỬA
```
bất kể điểm 4 mục.
Console
```
error
```
/
```
pageerror
```
/response
```
>= 400
```
/
```
requestfailed
```
→ ghi vào mục 4, không cho PASS.
Tiêu chí WCAG không tự-động được → ghi rõ "cần mắt người / nợ
```
[[150726-unknown-ledger]]
```
", không tự cho PASS.

无法启动 server/headless 时，engine fail-open（不阻止流程）；LLM audit 仍可运行，但必须注明可测量部分暂无数据。
route 上的用户任务无法完成时，无论四个板块得分如何，verdict 都为
```
需要修复
```
。
出现 console
```
error
```
/
```
pageerror
```
/response
```
>= 400
```
/
```
requestfailed
```
时，写入板块 4，不得判定为 PASS。
WCAG 条款无法自动检测时，必须明确写为「需要人工肉眼检查/待办
```
[[150726-unknown-ledger]]
```
」，不得自行判定为 PASS。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W00	judgment	route	Route là list/table? → nạp `references/list-control-checklist.md`	checklist bổ sung	không → bỏ qua
W01	deterministic	route, `<base-url>`	Xác định phạm vi + chạy engine `route-shots.mjs --audit` trước	issues theo route	không dựng được → fail-open, ghi chú
W02	judgment	issues + DOM	Chấm bốn mục: điểm/10 · lỗi nặng nhất · cách sửa	4 mục đủ ba phần	—
W03	deterministic	issues engine	Gắn dữ kiện engine vào mục có lỗi đo được	số đo dẫn nguồn	—
W04	judgment	4 mục	Kết luận `PASS` / `CẦN SỬA` (theo mục/route yếu nhất)	verdict + phải-sửa	—
W05	deterministic	UI đã sửa	Chạy lại engine chứng minh lỗi đo-được hết (đỏ→xanh)	engine xanh	còn đỏ → vẫn CẦN SỬA
W06	effect	kết quả	Ghi draft Output Report + index + log	draft	chỉ chạy engine → skip

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

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W00	judgment	route	route 是否为 list/table？→ 加载 `references/list-control-checklist.md`	补充 checklist	否 → 跳过
W01	deterministic	route、 `<base-url>`	确定范围，并优先运行 engine `route-shots.mjs --audit`	按 route 输出 issues	无法启动 → fail-open，并记录说明
W02	judgment	issues + DOM	对四个板块评分：评分/10 · 最严重问题 · 修复方法	四个板块均包含三个部分	—
W03	deterministic	engine issues	将 engine 证据附加到存在可测量错误的板块	测量数据及来源	—
W04	judgment	4 个板块	得出 `PASS` / `需要修复` 结论（依据最弱板块/route）	verdict + 待修复项	—
W05	deterministic	已修复的 UI	再次运行 engine，证明可测量错误已消除（红→绿）	engine 绿色	仍为红色 → 仍为 `需要修复`
W06	effect	结果	写入 draft Output Report + index + log	draft	仅运行 engine → 跳过

各步骤详情如下（W00–W06 的 source of truth）：

Phạm vi audit (mặc định = mockup/route hiện có)

Audit 范围（默认=当前 mockup/route）

Mặc định soi UI đang có — các route/trang mockup vừa dựng. User chỉ định route/màn thì soi cái đó. Đọc DOM + đo rect thật (getBoundingClientRect) qua engine; KHÔNG đoán từ CSS tĩnh (đọc CSS MÙ lỗi render — bài học 15/07/26).

默认审查当前 UI——刚搭建的 route/页面 mockup。用户指定 route/页面时，仅审查对应对象。通过 engine 读取 DOM 并测量真实 rect（getBoundingClientRect）；不得根据静态 CSS 猜测（读取 CSS 无法发现渲染错误——15/07/26 的经验）。

Steps

Route là list/table? (queue, admin grid, ticket/request list, dashboard summary strip) → load thêm
```
references/list-control-checklist.md
```
— 11 lỗi hay gặp riêng cho list/table (chồng hệ màu trên row, sort bucket, overflow-clip popover, mobile filter collapse…), mỗi lỗi đã gắn sẵn mục nào trong 4 mục dưới.
Xác định phạm vi — route/màn nào. Chạy engine tất định trước để có DỮ KIỆN đo được (mục "Engine" dưới).
Chấm bốn mục (mục dưới). Mỗi mục: điểm/10 · lỗi nặng nhất · cách sửa. → Xong khi cả bốn mục đủ ba phần.
Mục có lỗi ĐO ĐƯỢC: gắn dữ kiện engine (contrast fail ở đâu, control nào <24px, cặp nào overlap…) — số đo là dữ kiện, verdict là ý kiến.
Kết luận —
```
PASS
```
(sang bước kế) hay
```
CẦN SỬA
```
(liệt kê phải sửa gì). → Xong khi verdict rõ + danh sách phải-sửa nếu CẦN SỬA.
Chạy lại engine sau khi sửa để chứng minh lỗi đo-được đã hết (đỏ→xanh), giống test tái hiện của qc-code.

Route 是否为 list/table？（queue、admin grid、ticket/request list、dashboard summary strip）→ 额外加载
```
references/list-control-checklist.md
```
——其中包含 list/table 常见的 11 类问题（row 颜色重叠、sort bucket、overflow-clip popover、mobile filter collapse 等），每类问题都已预先归入下方四个板块。
确定范围——明确要审查的 route/页面。优先运行确定性 engine，以获得可测量的事实（见下方“Engine”）。
对四个板块评分（见下方）。每个板块：评分/10 · 最严重问题 · 修复方法。→ 四个板块都具备三个部分后完成。
为存在可测量错误的板块附加 engine 证据（contrast 在哪里失败、哪个 control 小于 24px、哪一对元素发生 overlap 等）——测量结果是事实，verdict 是意见。
得出结论——
```
PASS
```
（进入下一步）或
```
需要修复
```
（列出必须修改的内容）。→ verdict 明确，且在
```
需要修复
```
时列出待修复项后完成。
修复后再次运行 engine，证明可测量错误已经消除（红→绿），方式与 qc-code 的复现测试相同。

Bốn mục

四个板块

1. Accessibility (a11y) — điểm/10 · lỗi nặng nhất · cách sửa

1. Accessibility（a11y）——评分/10 · 最严重问题 · 修复方法

Soi (phần lớn ĐO ĐƯỢC — engine bắt): contrast (chữ thường ≥4.5:1, chữ lớn ≥3:1, control/viền/icon ≥3:1 — WCAG 2.2 AA) · tap-target (control tương tác ≥24×24px CSS là sàn AA 2.5.8; khuyến 44/48px mobile) · focus-visible (có vòng focus rõ, tương phản ≥3:1) · missing-label (nút/icon/link screen-reader đọc rỗng — thiếu aria-label/text). Đây là ranh giới tiếp cận — không lười (a11y là LUẬT, không phải gu). Lưu ý: chỉ ~30% tiêu chí WCAG tự-động được → phần còn lại (keyboard trap, thứ tự focus, alt có NGHĨA) là mắt người.

审查内容（大部分可测量，由 engine 捕获）：contrast（普通文字 ≥4.5:1、大号文字 ≥3:1、control/边框/icon ≥3:1——WCAG 2.2 AA）· tap-target（交互 control ≥24×24px CSS，这是 AA 2.5.8 的最低要求；mobile 建议 44/48px）· focus-visible（存在清晰的 focus ring，contrast ≥3:1）· missing-label（button/icon/link 的屏幕阅读器名称为空——缺少 aria-label/text）。这是可达性的边界——不得放宽（a11y 是规则，不是偏好）。注意：只有约 30% 的 WCAG 条款可以自动检测；其余条款（keyboard trap、focus 顺序、alt 是否有实际含义）需要人工肉眼检查。

2. Visual hierarchy — điểm/10 · lỗi nặng nhất · cách sửa

2. Visual hierarchy——评分/10 · 最严重问题 · 修复方法

Luật đo được (engine
fdk/tools/html-visual-gate.mjs
, PLAN 220926 — user 22/09/2026), chạy TRƯỚC khi LLM chấm mục này:

```
heading-scale
```
(FAIL): các cấp tiêu đề có mặt phải to → nhỏ (h1 > h2 > h3 > h4) và không nhỏ hơn chữ nội dung.
```
title-scale
```
(FAIL): tên trang (brand/logo/h1) ≥ 1,2 × chữ lớn nhất của mục nav và tab chọn nội dung.
```
sentence-case
```
(FAIL): tiêu đề, nhãn, nút, tab, mục nav viết hoa chữ đầu (tha định danh có số/-_./:@, tên riêng, chữ trong code; giữ chữ thường có chủ đích bằng
```
data-case="keep"
```
).
```
eye-rest
```
(WARN): phải có KHOẢNG NGHỈ CHO MẮT — màn đầu ≤ 55% là chữ/khối và không dải dày liền > 520px thiếu khoảng trống ≥ 24px; ngưỡng heuristic của framework. Nhồi nhiều thứ ngang hàng lên một màn (6 viên trạng thái + 3 chip + 3 nút trên một thanh) là lỗi dù từng thứ đúng — gộp, và để phần chi tiết hiện khi bấm (NN/g progressive disclosure).
```
kanban-uniform
```
(FAIL): bảng kanban (≥ 2 cột
```
lane|kanban|[data-kanban-lane]
```
) — mọi thẻ cùng rộng + cùng cao (±2px) và cùng style (nền · viền · bo · padding · font); thẻ cố định kích thước, bấm mới xem chi tiết.
Hài hòa nút (engine riêng
```
fdk/tools/button-harmony.mjs
```
, user 24/09/2026 — chạy ở 1440 VÀ 390, rc 0 mới được chấm PASS):
```
lone-action
```
(FAIL) nút đứng lẻ một dòng, không phải hàng kết thúc khối, trôi > 50% bề rộng hàng — nút phụ phải CÙNG DÒNG với tiêu đề/ô nó phục vụ;
```
edge-gap
```
(FAIL) hàng canh mép phải mà con cuối hụt mép > 8px;
```
empty-occupant
```
(FAIL) ô rỗng vô hình > 48px chiếm chỗ trong hàng ngang (tha phần tử đệm
```
flex:1
```
);
```
mixed-edge
```
(WARN) các hàng nút kết thúc trong một khối căn khác mép. Luật
```
action-left
```
(ưu tiên góc phải dưới) vẫn đúng — hài hòa là điều kiện THÊM, không thay nó. Trang cần đăng nhập: chụp DOM đã render ra file, gỡ script ứng dụng, rồi chạy trên file.
Chuẩn so sánh: mỗi phần UI đang audit có khối cùng loại trong trang mẫu
```
skills/hallmark/references/design-showcase.html
```
(máy khách:
```
~/.claude/skills/hallmark/references/design-showcase.html
```
). Lấy khối bằng
```
python3 fdk/tools/build-design-showcase.py --get <id>
```
(máy khách:
```
python3 ~/.claude/harness/fdk/tools/build-design-showcase.py --get <id>
```
;
```
--list
```
in index) rồi so từng điểm (kích thước, trạng thái, token màu, motion); lệch mà trang không khai miễn trừ = lỗi, ghi rõ id khối chuẩn trong "cách sửa".
Yêu cầu đặc biệt thì trang TỰ KHAI:
```
<meta name="overstack-exempt" content="heading-scale,…" data-reason="…">
```
— audit phải đọc lý do, không tự miễn. Soi (mắt LLM): nút trông như nút, link trông như link, heading phân cấp kích cỡ rõ (bắt user phải "giải mã" giao diện = fail) · CTA rõ ràng (hành động chính nổi bật, không mơ hồ) · content density (không nhồi quá nhiều lên một màn — quá tải = mất hierarchy). Chỉ ra đâu là điểm mắt dừng ĐẦU TIÊN và nó có đúng là hành động chính không.

可测量规则（engine
fdk/tools/html-visual-gate.mjs
，PLAN 220926——用户 22/09/2026），必须在 LLM 评分前运行：

```
heading-scale
```
（FAIL）：已存在的标题层级必须由大到小排列（h1 > h2 > h3 > h4），且不得小于正文。
```
title-scale
```
（FAIL）：页面名称（brand/logo/h1）≥ nav 最大文字和当前选中内容 tab 最大文字的 1.2 倍。
```
sentence-case
```
（FAIL）：标题、标签、button、tab 和 nav 项采用首字母大写形式（专有名词或包含数字/-_./:@ 的标识符、code 中的文本除外；通过
```
data-case="keep"
```
保留有意使用的小写形式）。
```
eye-rest
```
（WARN）：必须为眼睛留出休息空间——首屏中文字/块占比 ≤55%，且不得存在长度 >520px、却缺少 ≥24px 空隙的密集横带；这是 framework 的 heuristic。在同一屏横向塞入过多内容（一个横条中有 6 个状态卡 + 3 个 chip + 3 个 button）即构成问题，即使每个元素单独看都正确——应进行归组，并在点击后显示详情（NN/g progressive disclosure）。
```
kanban-uniform
```
（FAIL）：kanban 表格（≥2 列
```
lane|kanban|[data-kanban-lane]
```
）——所有卡片的宽度和高度必须一致（±2px），样式也必须一致（背景 · 边框 · 圆角 · padding · font）；卡片使用固定尺寸，点击后再查看详情。
Button harmony（独立 engine
```
fdk/tools/button-harmony.mjs
```
，用户 24/09/2026——必须在 1440 和 390 两种尺寸下运行，只有 rc 0 才能评为 PASS）：
```
lone-action
```
（FAIL）孤立 button 独占一行，既不是 block 的末尾行，也偏离行宽 >50%——次要 button 应与它所服务的标题/卡片位于同一行；
```
edge-gap
```
（FAIL）行按右侧对齐，但最后一个子元素与边缘偏差 >8px；
```
empty-occupant
```
（FAIL）不可见的空占位 >48px，仍占据横向行的空间（移除
```
flex:1
```
spacer）；
```
mixed-edge
```
（WARN）同一 block 中各 button 行的末尾对齐到不同边缘。
```
action-left
```
规则（优先右下角）仍然有效——harmony 是附加条件，不会将其替换。需要登录的页面：先将已渲染的 DOM 抓取到文件，移除应用 script，然后在文件上运行。
参考标准： 当前 audit 的每个 UI 部分，都应在样例页面
```
skills/hallmark/references/design-showcase.html
```
中找到同类型 block（客户端路径：
```
~/.claude/skills/hallmark/references/design-showcase.html
```
）。使用
```
python3 fdk/tools/build-design-showcase.py --get <id>
```
获取 block（客户端路径：
```
python3 ~/.claude/harness/fdk/tools/build-design-showcase.py --get <id>
```
；
```
--list
```
输出索引），然后逐项比较尺寸、状态、颜色 token 和 motion；除非页面明确声明豁免，否则任何偏差都视为问题，并在“修复方法”中注明标准 block 的 id。
页面有特殊要求时，必须自行声明：
```
<meta name="overstack-exempt" content="heading-scale,…" data-reason="…">
```
——audit 必须读取其理由，不得自行给予豁免。审查内容（LLM 肉眼判断）：button 看起来像 button，link 看起来像 link，heading 的尺寸层级清晰（如果用户必须“解码”界面，则为 fail）· CTA 清晰明确（主要操作突出，没有歧义）· content density（不能在同一屏塞入过多内容——过载会破坏 hierarchy）。指出视线首先停留的位置，并确认它是否对应主要操作。

3. Consistency (design-system) — điểm/10 · lỗi nặng nhất · bảng drift

3. Consistency（design-system）——评分/10 · 最严重问题 · drift 表

Soi (mắt LLM, vài phần đo được): spacing theo token (thang 4/8px — gap lộn xộn = mất nhịp) · màu nhất quán (không bảng màu chỏi/lẫn) · shadow (không lạm dụng/sai độ sâu — engine bắt

shadow-clipped

monochrome-surface

) · typography (cặp font/size nhất quán) · đồng nhất xuyên trang (cùng thứ gọi cùng kiểu ở mọi màn). Trả bảng drift:

Chỗ	Lệch chuẩn	Sửa về
card padding	14px / 20px / 17px lẫn lộn	token `--sp-4` (16px)

审查内容（主要由 LLM 完成，部分可测量）：spacing 使用 token（4/8px 阶梯——间距杂乱会破坏节奏）· 颜色一致（不得混用相互冲突的调色板）· shadow（不得滥用或使用错误深度——engine 会捕获

shadow-clipped

monochrome-surface

）· typography（字体和字号组合一致）· 跨页面一致（同一事物在所有页面中使用同一风格）。返回 drift 表：

位置	标准偏差	修复为
card padding	14px / 20px / 17px 混用	token `--sp-4` （16px）

4. Antipattern & interaction — điểm/10 · lỗi nặng nhất · bằng chứng đo

4. Antipattern & interaction——评分/10 · 最严重问题 · 测量证据

Soi: dark-mode readability (chữ washed-out quá nhạt/quá tối — lỗi dark-mode kinh điển, engine bắt qua contrast-aa ở theme tối) · hình học vỡ (overlap ≥4px, row-misalign — control chồng/không cao bằng nhau, engine ĐO rect) · feedback thiếu (hành động không có phản hồi hệ thống) · responsive vỡ (tràn ngang, chồng ở khổ hẹp) · dark-pattern (ép buộc, gài lựa chọn, khó thoát). Mỗi lỗi đo-được → dẫn số từ engine (route nào, cặp nào, chồng bao nhiêu px).

审查内容：dark-mode readability（文字 washed-out，过亮或过暗——dark-mode 的经典问题，engine 会通过主题下的 contrast-aa 捕获）· 几何布局损坏（overlap ≥4px、row-misalign——control 重叠或高度不一致，engine 测量 rect）· 反馈缺失（操作没有系统反馈）· responsive 损坏（窄视口下横向溢出或重叠）· dark-pattern（强制行为、诱导或锁定选择、难以退出）。每个可测量问题都必须引用 engine 数值（所在 route、对应元素、重叠多少 px）。

Kết luận (verdict)

结论（verdict）

Một trong hai, kèm lý do:

PASS — không lỗi nặng ở mục nào; a11y đo-được sạch; sang bước kế được.
CẦN SỬA — liệt kê cụ thể phải sửa gì (ưu tiên a11y đo-được + hình học vỡ trước hierarchy/consistency).

Verdict là ADVISORY — người quyết, không chặn commit. Thứ gác cứng là engine tất định (contrast/tap-target/overlap/misalign đỏ→xanh). Đừng để user tưởng "qc-uiux PASS = UI hoàn hảo"; nó là cặp mắt senior, không phải bằng chứng.

以下二者之一，并附理由：

PASS——任何板块均无严重问题；可测量的 a11y 干净；可以进入下一步。
需要修复——具体列出必须修改的内容（优先处理可测量的 a11y 和损坏的几何布局，其次才是 hierarchy/consistency）。

Verdict 属于 ADVISORY——供人决策，不阻止 commit。 真正的硬门禁是确定性 engine（contrast/tap-target/overlap/misalign 红→绿）。不要让用户误以为「qc-uiux PASS = UI 完美无缺」；它是一双 senior 之眼，而不是完整证据。

Engine tất định (0-token, KHÔNG LLM) — reuse visual-qa

确定性 engine（0-token、不使用 LLM）——复用 visual-qa

Phần ĐO ĐƯỢC dùng chung engine của

/visual-qa

(

skills/visual-qa/assets/route-shots.mjs

, headless playwright), hàm

DESIGN_AUDIT

đo rect thật trong trang và bắt các rule:

contrast-aa

tap-target

missing-label

overlap

row-misalign

shadow-clipped

monochrome-surface

rogue-slab

. Chạy:

bash

node skills/visual-qa/assets/route-shots.mjs <base-url> --audit    # in issues theo route; exit ≠0 nếu a11y/hình học fail

Đây là phần "tự động hook khi UI đổi" — chỉ hook phần rẻ tất định, LLM audit (skill này, 4 mục) giữ gọi tay. Fail-open nếu chưa dựng được server/headless (không chặn). Giống

qc-regression.py --run

của qc-code:

verify-before-commit

bước 3b gọi nó; UI đổi → antipattern đo-được không âm thầm quay lại.

可测量部分复用

/visual-qa

的 engine（

skills/visual-qa/assets/route-shots.mjs

，headless playwright）。

DESIGN_AUDIT

函数会测量页面中的真实 rect，并捕获以下 rules：

contrast-aa

tap-target

missing-label

overlap

row-misalign

shadow-clipped

monochrome-surface

rogue-slab

。运行：

bash

node skills/visual-qa/assets/route-shots.mjs <base-url> --audit    # in issues theo route; exit ≠0 nếu a11y/hình học fail

这是“UI 发生变化时自动 hook”的部分——仅 hook 便宜的确定性部分；LLM audit（当前 skill 的四个板块）仍采用手动调用。如果尚未启动 server/headless，则 fail-open（不阻止流程）。其模式与 qc-code 的

qc-regression.py --run

相同：

verify-before-commit

的步骤 3b 会调用它；UI 改动后，可测量的 antipattern 不会悄悄回归。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	route là list/table (queue, admin grid, ticket/request list, dashboard summary strip)	nạp `references/list-control-checklist.md` , 11 lỗi gắn sẵn vào 4 mục	route khác → skip	W01
B02	recovery	không dựng được server/headless	engine fail-open (không chặn), audit LLM tiếp, ghi phần đo được là chưa có số	—	W02
B03	conditional_required	route có tác vụ người dùng (submit, checkout, đăng nhập) không hoàn thành được	verdict `CẦN SỬA` bất kể điểm 4 mục	—	W04

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	conditional_required	route 为 list/table（queue、admin grid、ticket/request list、dashboard summary strip）	加载 `references/list-control-checklist.md` ，将 11 类问题预先归入四个板块	其他 route → skip	W01
B02	recovery	无法启动 server/headless	engine fail-open（不阻止流程），LLM audit 继续执行，并注明可测量部分暂无数据	—	W02
B03	conditional_required	route 包含无法完成的用户任务（submit、checkout、登录）	无论四个板块得分如何，verdict 均为 `需要修复`	—	W04

Validation và stopping

Validation 与 stopping

Phần đo được (contrast, tap-target, overlap, misalign, missing-label…) do engine tất định quyết, exit ≠0 khi fail; phần hierarchy/drift/dark-pattern là review LLM, verdict chỉ advisory. Dừng khi 4 mục đủ ba phần + verdict rõ; sau sửa, engine phải xanh (W05).

可测量部分（contrast、tap-target、overlap、misalign、missing-label 等）由确定性 engine 决定，失败时 exit ≠0；hierarchy/drift/dark-pattern 由 LLM review，verdict 仅作为 advisory。四个板块都具备三个部分且 verdict 明确后停止；修复后，engine 必须变为绿色（W05）。

Examples

Positive:
```
/qc-uiux
```
sau
```
/br run
```
frame form đăng ký → engine sạch, 4 mục 8–9/10, lỗi nặng nhất mục 3 là card padding 14/20/17px → bảng drift về
```
--sp-4
```
→ verdict
```
PASS
```
, draft
```
DDMMYY-qc-uiux-signup.md
```
.
Boundary/failure: dark mode chữ phụ contrast 2.8:1 + nút icon 20×20px → engine
```
contrast-aa
```
+
```
tap-target
```
fail có số → mục 1 lỗi nặng nhất + cách sửa →
```
CẦN SỬA
```
; sửa xong chạy lại engine phải xanh.
Boundary: trang đẹp, 4 mục điểm cao nhưng nút submit ném
```
pageerror
```
→ mục 4 ghi lỗi, verdict
```
CẦN SỬA
```
.

Positive： 在
```
/br run
```
生成注册表单 frame 后执行
```
/qc-uiux
```
→ engine 干净，四个板块得分 8–9/10，板块 3 的最严重问题是 card padding 分别为 14/20/17px → drift 表将其统一为
```
--sp-4
```
→ verdict 为
```
PASS
```
，生成 draft
```
DDMMYY-qc-uiux-signup.md
```
。
Boundary/failure： dark mode 下辅助文字 contrast 为 2.8:1，且 icon button 为 20×20px → engine 报告
```
contrast-aa
```
+
```
tap-target
```
fail 并提供数值 → 板块 1 给出最严重问题和修复方法 →
```
需要修复
```
；修复后再次运行 engine，必须变为绿色。
Boundary： 页面美观，四个板块得分也很高，但 submit button 抛出
```
pageerror
```
→ 板块 4 记录该错误，verdict 为
```
需要修复
```
。

Reference — Related

Reference——Related

```
references/list-control-checklist.md
```
— 11 lỗi riêng cho list/table (đọc Steps bước 0).
```
skills/visual-qa/assets/route-shots.mjs
```
— engine đo tất định (DESIGN_AUDIT) mà skill này reuse.
```
llmwiki/skills/dev-loop/qc-code.md
```
— skill anh em: cùng khuôn đắt-LLM / rẻ-tất-định, cho CODE.
```
harness/scripts/qc-regression.py
```
— runner test qc-* tất định (qc-code) chạy ở verify-before-commit.

llmwiki/skills/dev-loop/build-now-adapt-later.md

— quA khuôn tách quarantine đắt/rẻ.

```
references/list-control-checklist.md
```
——list/table 专用的 11 类问题（见 Steps 的步骤 0）。
```
skills/visual-qa/assets/route-shots.mjs
```
——当前 skill 复用的确定性测量 engine（
```
DESIGN_AUDIT
```
）。
```
llmwiki/skills/dev-loop/qc-code.md
```
——同类 skill：采用相同的“昂贵 LLM/便宜确定性”模式，但用于 CODE。
```
harness/scripts/qc-regression.py
```
——确定性 qc-* test runner（qc-code），在 verify-before-commit 阶段运行。
```
llmwiki/skills/dev-loop/build-now-adapt-later.md
```
——采用同样 quarantine 昂贵/便宜模式的指南。

Delivery — Output Report

Delivery——Output Report

Sau khi audit xong, ghi draft

llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md

(OKF frontmatter

type: draft

## Origin

) tóm: route đã soi · điểm 4 mục · lỗi đo-được từ engine · verdict + phải-sửa. Thêm dòng vào

index.md

log.md

. Bỏ qua nếu chỉ chạy engine đo (không có phán đoán mới).

Audit 完成后，写入 draft

llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md

（使用 OKF frontmatter

type: draft

、

## Origin

），内容摘要包括：已审查的 route · 四个板块的评分 · engine 提供的可测量错误 · verdict + 待修复项。同时向

index.md

log.md

添加记录。如果仅运行测量 engine，且没有产生新的判断，则跳过。