qc-uiux
Audit UI/UX phong cách SENIOR — bốn mục accessibility · visual-hierarchy · consistency · antipattern, mỗi mục cho ĐIỂM/10 + LỖI NẶNG NHẤT + CÁCH SỬA, rồi một kết luận PASS-sang-bước-kế hay CẦN-SỬA. Phần ĐO ĐƯỢC (contrast WCAG, tap-target, overlap/misalign hình học, missing-label) chạy tất định qua engine visual-qa (headless, 0-token, KHÔNG LLM); phần cần MẮT (hierarchy, drift design-system, dark-pattern) là LLM audit. Gọi khi user nói "qc uiux", "audit ui", "soi giao diện", "dẹp antipattern ui", "/qc-uiux", hoặc SAU khi có mockup/UI. NHÂN KHUÔN /qc-code (đắt=LLM tay, rẻ=test tất định auto). KHÁC /redesign (đổi mới thẩm mỹ) và /visual-qa (chụp+gác pixel) — qc-uiux là verdict senior 4-mục.
How do I install this agent skill?
npx skills add https://github.com/rheinmir/setup --skill qc-uiuxIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is generally safe but has a vulnerability surface for indirect prompt injection because it ingests untrusted data from external websites (DOM, CSS, console logs) without sanitization or boundary markers. It also executes internal utility scripts to perform UI measurements.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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-workflowtrướcverify-before-commit, và tự-động sau mỗi/br runframe có UI. - User nói "qc uiux", "audit ui", "soi giao diện", "dẹp antipattern ui", "/qc-uiux".
- Vừa dựng/đổi UI (mockup
- 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
qacủ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 → verdictCẦN SỬAbấ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-verifyRules). 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ỬAbấ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ế) hayCẦ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ằngdata-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ộtlane|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ử đệmflex: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ậtaction-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ằngpython3 fdk/tools/build-design-showcase.py --get <id>(máy khách:python3 ~/.claude/harness/fdk/tools/build-design-showcase.py --get <id>;--listin 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:
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-uiuxsau/br runframe 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→ verdictPASS, draftDDMMYY-qc-uiux-signup.md. - Boundary/failure: dark mode chữ phụ contrast 2.8:1 + nút icon 20×20px → engine
contrast-aa+tap-targetfail 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, verdictCẦ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).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/rheinmir/setup/qc-uiux">View qc-uiux on skillZs</a>