skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
rheinmir/setup79 installs

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-uiux
view source ↗

Is 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-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

FieldRequired?Ý nghĩa
Inroute/mànkhông (mặc định = mockup/route hiện có)user chỉ định thì soi cái đó
In<base-url> chạy đượccó cho phần đoengine headless cần server; không dựng được → fail-open
Inloại route (list/table?)tự xác địnhcó → nạp references/list-control-checklist.md
Out4 mục × điểm/10 · lỗi nặng nhất · cách sửacómục 3 kèm bảng drift; mục có lỗi đo được dẫn số engine
OutverdictcóPASS hoặc CẦN SỬA + danh sách phải sửa — ADVISORY
Outdraft llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md + index + logcó (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

StepTypeInputsActionOutputs/exitFailure/next
W00judgmentrouteRoute là list/table? → nạp references/list-control-checklist.mdchecklist bổ sungkhông → bỏ qua
W01deterministicroute, <base-url>Xác định phạm vi + chạy engine route-shots.mjs --audit trướcissues theo routekhông dựng được → fail-open, ghi chú
W02judgmentissues + DOMChấm bốn mục: điểm/10 · lỗi nặng nhất · cách sửa4 mục đủ ba phần—
W03deterministicissues engineGắn dữ kiện engine vào mục có lỗi đo đượcsố đo dẫn nguồn—
W04judgment4 mụcKết luận PASS / CẦN SỬA (theo mục/route yếu nhất)verdict + phải-sửa—
W05deterministicUI đã sửaChạy lại engine chứng minh lỗi đo-được hết (đỏ→xanh)engine xanhcòn đỏ → vẫn CẦN SỬA
W06effectkết quảGhi draft Output Report + index + logdraftchỉ 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

  1. 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.
  2. 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).
  3. 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.
  4. 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.
  5. 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.
  6. 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ẩnSửa về
card padding14px / 20px / 17px lẫn lộntoken --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

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredroute 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ụcroute khác → skipW01
B02recoverykhông dựng được server/headlessengine fail-open (không chặn), audit LLM tiếp, ghi phần đo được là chưa có số—W02
B03conditional_requiredroute có tác vụ người dùng (submit, checkout, đăng nhập) không hoàn thành đượcverdict 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).

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>