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.

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

Input và 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

Rules và 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.

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.

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

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

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

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.

Bốn mục

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

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.

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

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.

3. Consistency (design-system) — điểm/10 · lỗi nặng nhất · bảng 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)

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

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

Kết luận (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.

Engine tất định (0-token, KHÔNG LLM) — reuse 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.

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

Validation và 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).

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

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

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

qc-uiux

NPX Install

Tags

SKILL.md Content