DOL UI Quality Audit - Vision-first review rubric

activeUpdated3 tuần trước

AUDIT - Vision-first UI quality review

Mission: Đánh giá UI bằng mắt trước khi đánh giá bằng code. Output prescriptive (đề xuất fix) chứ không chỉ chẩn đoán. Áp dụng cho mọi surface DOL hoặc external project consume DS-Token.

0. When this rubric applies

Dùng AUDIT.md khi:

Bạn có 1 screenshot / URL / Figma node / live-preview của UI surface
Bạn muốn biết: UI này có “đúng feel DOL” chưa? Có dính slop không? Code có lệch CORE.md không?
Output cần: prescriptive (đề xuất fix), không chỉ liệt kê lỗi

KHÔNG dùng khi:

Audit code-only (no visual context) → audit.sh text-only đủ
Token math / contrast verification → contrast-check.py + spec.sh
Generic non-DOL web standards → web-design-guidelines skill (Vercel rules)

1. Triết lý của audit

Code đúng KHÔNG đủ. Một UI có thể pass audit.sh + dùng đúng bg-brand-600 nhưng vẫn feel sai DOL - cold, busy, generic, AI-templated. Vì vậy audit này đi từ cảm giác → cấu trúc → chi tiết - match thứ tự user thật sự perceive UI:

Mở UI, 2-second impression - FEELING
Scan quanh, parse hierarchy + intent - DIRECTION
Đối chiếu structure: spacing, alignment, density - COMPOSITION
Soi class names, tokens, code - TOKEN/CODE

Layer 1-2 weighted heavier - chúng define experience. Layer 3-4 là how-to-fix layer. Một UI fail L1-L2 nhưng pass L4 vẫn là UI hỏng. Một UI fail L4 nhưng pass L1-L2 = vấn đề kỹ thuật cần dọn, nhưng chưa critical UX.

2. Rubric 4-layer

L1 - FEELING (cảm giác đầu tiên, 2 giây)

Hỏi (without zooming, without reading copy):

Industry test: Bạn nghĩ UI này thuộc industry nào nếu không có logo? DOL = education premium-but-warm. KHÔNG phải fintech (cold), B2B SaaS (sterile), casino (loud), children’s app (rainbow).
Tone: calm vs busy? trustworthy vs flashy? premium vs cheap?
AI-tell instant?: có pattern reveal “AI made this” trong 1 cái nhìn? (templated icon-tile-above, gradient text, side-stripe accent, all-centered siblings, etc. - full list DIRECTION.md §10 AI Slop fingerprints)
Focal point: có 1-2 element dẫn mắt không? hay everything-equal (slop-04 monotonous-spacing + grid-no-focal-point)?
Energy: rộng rãi-thoáng-đãng (đúng DOL) hay cramped/claustrophobic?

→ Cite: DIRECTION.md §1 Triết lý (cảm giác mục tiêu) + §10 AI Slop fingerprints.

L2 - DIRECTION (philosophy alignment)

Đối chiếu 4 core pillars + handoff checklist:

Semantic-first - token semantic được dùng trước, không hardcode hex/raw values? (DIRECTION.md §2)
Variable-first styling - variable là default, không lạm dụng paint/effect style? (§3)
Soft-large radius - controls feel “mời chạm” not “laser-cut enterprise”? (§8)
Generous spacing - breathing room, không cramped? (§7)
Brand color discipline - bg-brand-* cho brand, bg-red-* cho danger only? Không quá 2 semantic accents per view? (§4)
CVD-aware - blue + purple cùng nhau có pair với icon shape khác + label? (§5)
Typography 2-fonts - Plus Jakarta Sans (heading) + Inter (body), body baseline 14px, ≤3 cấp font-size per card? (§6)
Match-and-refuse - có row nào trong §10 sub-tables match với UI đang xem không? Nếu có → STOP, rewrite approach (không chỉ swap value).

Apply §12 Handoff checklist (10 smell tests) thẳng vào ảnh - mỗi câu trả “không chắc” = 1 finding L2.

L3 - COMPOSITION (cấu trúc + layout)

Visual structure level:

Hierarchy 2-second test passed? (mắt user biết đọc gì trước, gì sau, gì optional)
Spacing rhythm - atom/molecule/organism/section có nhịp riêng? (spacing.md §A-D) hay slop-04 monotonous-spacing (cùng gap-4 everywhere)?
Alignment - left-align body, asymmetric composition cho variety? hay slop-05 everything-centered (multiple consecutive text-center siblings)?
White-space discipline - breathing room hay claustrophobic? Whitespace là content (DIRECTION §7).
Card depth - flatten OK hay slop-03 nested-cards (Card chứa Card cùng treatment)?
Consistency - same element same style xuyên view? Khác = user hỏi “sao 2 cái này khác?”
Density taxonomy - đúng fit/compact/standard/extended cho context? (typography.md) Lưu ý: fit chỉ cho text trang trí 1 dòng, không cho content cần đọc.
Section breaks - section liền nhau có khoảng cách rõ? (slop direction-10-layout #03)

L4 - TOKEN / CODE (technical correctness)

Last layer - chỉ matter nếu L1-L3 đã ổn (nếu L1-L3 fail, fix code chỉ là band-aid):

Tailwind class match CORE.md recipe? (CORE.md §9 Component Recipes)
Canonical shade -600 (NOT -500)? (CORE.md §2 Color)
Neutral = slate-* only - không gray-*/zinc-*/neutral-*? (CORE.md §2)
Static class strings - không bg-${color}-600 interpolation (TW scanner tree-shake mất)? (.claude/rules/ui-style.md)
No var(--token) / bg-(--token) trong class attributes? (.claude/rules/ui-style.md)
Border on white-on-white - border-slate-200 mandatory (default); hover → border-slate-300; shadow bổ trợ không thay border? (border-slate-100 only for lighter section-to-section dividers per CORE.md §8.2.) (CORE.md §8.1)
Tab/segmented container - bg-slate-50 (không bg-slate-100)? (CORE.md §6)
Anti-pattern registry - có vi phạm row nào trong anti-pattern-registry.md? Cite scope#NN.
Skeleton sections - nếu UI dùng product-extension nhưng section đó status:skeleton, code phải compose từ CORE primitives, KHÔNG invent canonical mới.

🛑 L4 anti-pattern when reviewing: KHÔNG lặp lại finding mà audit.sh đã catch sẵn (nó chạy pre-commit). Vision audit phụ trách slop-03/04/05/06 + L1-L3 + L4 chỉ những thứ static scan không thấy (vd: shade-500 thay vì -600 trong context vivid).

3. Output format

Header summary (bắt buộc, 1 dòng)

Overall feel: <1 sentence - what this UI feels like to a first-time visitor>
Top concern: <single highest-impact finding across L1-L4>

Per-layer table (max 3-5 rows mỗi layer)

LAYER	PATTERN	WHY (DOL context)	REWRITE	CITE
L1		<DOL-specific reason, not generic UX>	<concrete fix, not vague>	`DIRECTION.md §X` / `slop-NN`

Order: L1 → L2 → L3 → L4. Skip layer if no concern (state “L3: rhythm OK, no concern” 1 dòng).

Cap: max 5 rows per layer. Nếu thấy >5 → group + report top 5 by impact. Under-report > over-report (audit giữ trust).

4. Tone discipline

DO

✅ Cite canonical: “vi phạm DIRECTION.md §10 slop-06 icon-tile-above” - không paraphrase
✅ Đề xuất concrete: “thay icon box w-12 h-12 bg-blue-50 rounded-xl bằng inline lucide-Sparkles cạnh heading”
✅ Nói WHY trong DOL context: “tile-above feels templated trong education context - DOL muốn ‘professional ấm’ không ‘feature grid generic’”
✅ Suggest, đừng dictate - designer/dev có quyền argue back với rationale
✅ Sáng tạo: nếu thấy 1 fix tốt hơn cả CORE.md recipe hiện tại, propose nó + flag candidate cho promotion (R-future)

DON’T

❌ Liệt kê >5 finding mỗi layer (noise dilution → user tune out → audit mất giá trị)
❌ Bắt bẻ từng class minor (px-4 vs px-3.5 mà không tác động hierarchy)
❌ Generic UX rule (Nielsen, Apple HIG, Material) không tie vào DOL DIRECTION
❌ Lặp finding mà audit.sh đã catch (pre-commit static - không cần verbose lại)
❌ “This is bad” không có WHY + REWRITE
❌ Apply checklist robotically - surface tĩnh không cần audit motion (slop-08); landing page không cần audit form pattern; v.v. Skip irrelevant layer.

5. Output mode

Default: in-chat ephemeral output (no file written). User đọc, decide, action.

File mode: chỉ write file khi

User explicit: “save audit report”
Cross-surface batch (audit nhiều surface 1 lần) → cần aggregator file
CI pipeline chạy audit (future)

File path convention nếu write:

ai-memory/audit-reports/<surface-slug>-<YYYY-MM-DD>.md

Frontmatter bắt buộc:

---
audit_target: <screenshot-path | URL | figma-node-id>
audit_date: YYYY-MM-DD
auditor: <agent-name | reviewer-name>
overall_verdict: <1 sentence>
findings_count: { L1: N, L2: N, L3: N, L4: N }
---

6. Anti-patterns OF the audit itself

❌ Audit anti-pattern	Why bad	✅ Do
List 20+ findings	Noise → user ignore audit → mechanism erodes	Max 3-5/layer; pick highest-impact
Skip L1 (feeling) → jump to code	Misses point - user thấy feel trước code	Always state L1 first, dù chỉ “feel ổn, no concern”
Cite generic UX rule (Nielsen) without DOL anchor	DOL context lost; output nhạt nhòa, không tự tin	Cite `DIRECTION.md §X` first; UX rule chỉ supplementary
”Add more whitespace” without spec	Vague = unactionable → designer/dev frustrated	”Tăng `gap-3` → `gap-6` per `spacing.md` molecule level”
Repeat audit.sh findings verbose	audit.sh đã chạy pre-commit; lặp = wasted attention	Vision audit covers slop-03/04/05/06 + L1-L3; static covers L4 syntactic
Audit chỉ point lỗi không suggest fix	Diagnose ≠ prescribe; user còn phải tự figure out	Mỗi finding có REWRITE column non-empty
Apply rubric robotically (mọi layer luôn fill)	Layer irrelevant vẫn fill = noise	Skip layer + 1-line note “L3 rhythm OK”
Fabricate citation (cite section không tồn tại)	Trust crash; future audits questionable	Only cite sections you verified via Read tool
Print verify gate checklist (`[x] cite OK, [x] REWRITE OK...`) ra output	Verify là internal step để AI tự revise; in ra = bureaucratic noise, không add value cho user	Run verify silently; nếu fail → revise output trước khi return; KHÔNG print checklist
Append “Self-evaluation” / “Đánh giá meta” / câu hỏi feedback ở cuối audit	Skill solicit user judgment = đẩy work ngược về user; user judge tự nhiên qua phản hồi tiếp theo	Output ends at L4 row (hoặc skip note). Để user lead refinement nếu cần.
L4 partial-flag verbose (“cần Read TSX để complete…” 4 dòng recommend)	Nếu user paste screenshot mà không paste code, audit visual đủ; verbose hedge = noise	1-line skip note: “L4: visual clean; full code audit cần Read TSX riêng nếu user yêu cầu”

7. How external projects use this

Project ngoài DOL workspace mà consume DS-Token (CSS vars, Tailwind preset, hoặc Figma library):

Đọc thẳng AUDIT.md (file này) - portable, không Claude-specific, không cần workspace tooling.
Apply rubric 4-layer manually - designer/PM/AI nào cũng follow được.
Cite cùng canonical files trong report:
- DOL-DS-token/design-guideline/ds-guideline/DIRECTION.md (philosophy + slop catalog)
- DOL-DS-token/design-guideline/ui-style-guide/CORE.md (code recipes)
- Product extensions nếu surface match: landing.md / practice.md / data-entry.md
Optional: copy audit.sh vào project nếu cần static scan cùng pattern set.

Trong DOL workspace với Claude Code: skill ui-quality-audit auto-trigger trên audit phrases - không cần đọc file này manually trừ khi muốn verify rubric.

8. Maintenance contract (chống dư rác)

Để AUDIT.md không thành “another doc that goes stale”:

✅ AUDIT.md KHÔNG hard-code rule values - chỉ cite section anchors. DIRECTION.md / CORE.md đổi → audit auto-cập nhật vì cite by section name, không snapshot.
✅ Quarterly review only: thêm pattern mới vào AUDIT.md CHỈ khi pattern đó xuất hiện ≥2 surface. Premature codification = bloat.
✅ When DIRECTION.md / CORE.md restructure (rename section, đổi anchor): grep DIRECTION.md § + CORE.md § trong AUDIT.md để cập nhật cite paths. 1-time small task.
✅ Version bump: nếu rubric structure đổi (vd thêm L5), bump updated: frontmatter + ghi changelog 1 dòng cuối file.
❌ Do NOT copy content từ DIRECTION.md / CORE.md vào đây - duplicate = drift risk.
❌ Do NOT add layer mới mà không có evidence ≥3 finding fall ngoài L1-L4 hiện tại.

9. Quick example (mock - chưa fed real screenshot)

Overall feel: Education-app vibe but feels templated; landing-style hero không match DOL "professional ấm" (more "AI-generic feature grid").
Top concern: L1 slop-06 icon-tile-above pattern × 4 features → instant AI-tell.

L1 - FEELING
| PATTERN | WHY | REWRITE | CITE |
| Icon-tile box (w-12 h-12 rounded bg-blue-50) lặp 4 lần đầu mỗi feature | Templated, "AI-made" tell instant; feels generic SaaS landing không phải DOL education | Bỏ icon box; dùng inline `lucide-Sparkles` cạnh heading + body 14px slate-600 | `DIRECTION.md §10 slop-06` |
| Hero copy + CTA + image stack center, không asymmetric | slop-05 everything-centered; mắt không có rest point, mọi thứ ngang priority | Left-align hero copy, image bên phải, CTA pair-button bottom-left | `DIRECTION.md §10 slop-05` |

L2 - DIRECTION
| PATTERN | WHY | REWRITE | CITE |
| 3 màu accent simultaneously (brand, blue, purple icons) | DIRECTION §4 cap = 2 semantic accents per view | Giữ brand cho CTA + 1 accent (blue cho icons), bỏ purple | `DIRECTION.md §4` |

L3 - COMPOSITION
- Spacing rhythm OK (varied gap-3/gap-6/gap-12), no concern.

L4 - TOKEN/CODE
| PATTERN | WHY | REWRITE | CITE |
| `bg-blue-500` shade thay vì `-600` cho icon background tint | Canonical shade DOL = -600; -500 nhạt mất signal | Đổi `bg-blue-500` → `bg-blue-50` (subtle tint) hoặc `bg-blue-600/10` (alpha) | `CORE.md §2` |

10. Changelog

Date	Change
2026-04-25	v1 - initial 4-layer rubric, output format, tone discipline, maintenance contract