🔬 UX Research — Deep Analysis & System Audit
Skill nghiên cứu UX chuyên sâu, tổng hợp best practices từ 7 hệ thống thiết kế lớn nhất thế giới. Dùng để audit, maintain, và cải tiến hệ thống Prisma Design System.
How to Use This Skill
This skill is organized in 4 layers — start from the fastest and go deeper only when needed:
- 🚀 Knowledge Index (fast-path) —
knowledge/*.jsonfiles. Read these FIRST for 90% of UI/UX questions. They route to the right rules, tokens, and blueprints without reading this full skill. - This file (SKILL.md) — Domain overview, rule index, audit workflow, scoring. Read for audit context or rule deep-dive.
- references/ — Deep-dive rules per domain. Read only the domains relevant to your task.
- Automated scripts — Run the DS scripts listed at the bottom for machine-checkable rules.
⚡ Fast Path (use FIRST for most questions)
| Question Type | Index File | What You Get |
|---|---|---|
| "Build a settings page" | knowledge/problem-taxonomy.json → A1.settings |
Components, rules, approach, blueprint PP-003 |
| "Modal hay Dialog?" | knowledge/decision-trees.json → DT-005 |
Question flow → answer with tokens + ARIA |
| "Dashboard cần structure gì?" | knowledge/page-patterns.json → PP-002 |
Full stacking tree, responsive strategy, HTML skeleton |
| "Module title dùng token nào?" | knowledge/token-recommender.json → typography.module-title |
var(--font-size-base) 16px semibold, rules [T10, T14] |
| "UX checklist cho form?" | knowledge/token-recommender.json → ux_checklists.form_design |
12 pre-filtered rules |
Only fall back to this SKILL.md when you need: full rule explanation, audit scoring, edge cases, or reference system citations.
Deep-dive navigation:
- Auditing a full system? → Read the Audit Framework section, then reference files as needed
- Reviewing a specific component? → Jump to the relevant domain summary, then read its reference file
- Need a specific rule? → Use the Rule Index below to find it, then check its reference file
Reference Systems
| # | System | Abbr | Core Focus |
|---|---|---|---|
| 1 | Material Design 3 | MD3 | Component anatomy, states, motion physics, density, adaptive layout |
| 2 | Apple HIG | HIG | Clarity/Deference/Depth, Dynamic Type, spring animation, platform-native |
| 3 | shadcn/ui | SCN | bg/fg pairs, CSS var theming, composable components, Radix primitives |
| 4 | Carbon Design System (IBM) | CBN | UX governance, error handling, content guidelines, data viz |
| 5 | Ant Design | ANT | Information density, enterprise patterns, form validation, ProComponents |
| 6 | Atlassian Design System | ADS | Team-based UX, notification hierarchy, progressive disclosure |
| 7 | Nielsen Norman Group | NNG | 10 Usability Heuristics, cognitive load, error recovery, research |
Domain Index & Critical Rules
Each domain below lists its most critical rules (🔴). For the complete rule set with examples, decision trees, and checklists, read the referenced file.
§1. Visual Hierarchy & Color System
📖 Full rules: references/domains-visual-interaction.md §1
5 hierarchy levels: L1 Primary → L2 Secondary → L3 Tertiary → L4 Decorative → L5 Hidden (sr-only)
| ID | Critical Rule | Auto-check |
|---|---|---|
| C1 | Every color maps to a semantic role (primary, destructive, warning, etc.) | ✅ token-reviewer |
| C2 | Every background has a paired foreground (bg/fg pairs) | ✅ token-reviewer |
| C3 | Contrast: Text ≥4.5:1, Large text ≥3:1, UI ≥3:1 | ✅ Contrast checker |
| C4 | Never use color alone to convey meaning — always add icon/text | Manual |
| C5 | All semantic colors must have light + dark mode variants | ✅ token-reviewer |
§2. Interaction Principles
📖 Full rules: references/domains-visual-interaction.md §2
Nielsen's 10 Heuristics applied to DS. Key enforcement points:
| ID | Critical Rule | Enforcement |
|---|---|---|
| H1 | Every action → feedback within ≤100ms (visual) or ≤300ms (result) | §9 Motion |
| H3 | Every flow has a clear exit (Close, Cancel, Undo) | §10 States |
| H5 | Validate input before submit; disable invalid actions | §10 Errors |
6 interaction states (MD3 State Layer Model): Enabled → Hover (0.08) → Focused (0.10) → Pressed (0.10) → Dragged (0.16) → Disabled (0.38)
Touch rules: Min target 44×44px (HIG) or 24×24px (WCAG AA), cursor:pointer on clickable, double-click guard on async.
§3. Navigation & Information Architecture
📖 Full rules: references/domains-nav-layout-component.md §3
3 core nav styles (HIG): Hierarchical, Flat, Content-driven
| ID | Critical Rule |
|---|---|
| N1 | Max 5 top-level nav items on mobile |
| N3 | User always knows "where am I" (active state, breadcrumb on web) |
| N4 | Every drill-down has a clear back button |
| N7 | Active nav item has visual indicator (color, weight, underline) |
| N8 | Nav placement consistent across all pages |
| N9 | Breadcrumb = Web only — KHÔNG dùng breadcrumb trên mobile app, thay bằng back button + title |
IA principles: Progressive Disclosure, Chunking (7±2), Flat > Deep hierarchy.
§4. Layout & Spacing System
📖 Full rules: references/domains-nav-layout-component.md §4
Prisma 4-tier system: Page → Section → Group → Comp (each tier has own tokens)
| ID | Critical Rule |
|---|---|
| S1 | No hardcoded px/rem for spacing — always use tokens |
| S2 | All spacing is multiples of 4px base unit |
| S6 | Slot padding inherits from parent group, never hardcode |
| S8 | No internal dividers on surface containers (dialog/modal/drawer/card) — use spacing + subtle bg change instead |
§5. Component Behavior Rules
📖 Full rules: references/domains-nav-layout-component.md §5
Universal component contract: RENDER → INTERACT → STATE → FEEDBACK → COMPOSE → TOKEN
| ID | Critical Rule |
|---|---|
| B1 | Container components use .slot-header/.slot-body/.slot-footer anatomy |
| B2 | Overlay z-index uses tokens, never hardcode |
| B3 | Modal/dialog traps focus inside when open |
| B7 | Every overlay closes on Escape key |
Button size rules (BS-1→BS-5): Default = md (Medium). CTA = lg. Action group must use same size. See components md/button.md §4.7.
| ID | Critical Rule |
|---|---|
| BS-1 | Default = Medium — no modifier = md. CẤM dùng .btn-lg mặc định |
| BS-2 | CTA hierarchy — max 1-2 .btn-lg per view |
| BS-3 | Size pairing — action group buttons PHẢI cùng size |
| BS-4 | Mobile CTA — .btn-lg.btn--block on mobile (≤768px) |
| BS-5 | Form consistency — all form buttons same size (recommend md) |
Action group placement (AG-1→AG-7): Web = trailing (flex-end), App = center (full-width). See components md/button.md §4.8.
| ID | Critical Rule |
|---|---|
| AG-1 | Web trailing — action group justify-content: flex-end |
| AG-2 | App center — mobile app buttons center, full-width |
| AG-3 | Button order — Cancel trước, Confirm sau |
Component categories: Form Controls, Action Controls, Selection Controls, Containers, Feedback, Navigation, Data Display — each with specific rules in the reference file.
§6. Typography & Content Rules
📖 Full rules: references/domains-typography-a11y-responsive.md §6
Title hierarchy (Stacking Tier Mapping):
Page → h1: 30px bold ← --text-style-heading-1
Section → h2: 24px semibold ← --text-style-heading-2
Section → h3: 20px semibold ← --text-style-heading-3
Group → title: 16px semibold ← --font-size-base ★ T10
Overlay → title: 18px semibold ← --font-size-lg ★ T11
Comp → label: 14px medium ← --font-size-sm| ID | Critical Rule |
|---|---|
| T1 | Body text ≥14px desktop, ≥16px mobile |
| T4 | One <h1> per page, heading levels never skip |
| T5 | No hardcoded font-family — always use typography tokens |
| T9 | text-transform: uppercase ONLY for tiny UI labels (badge, tag ≤2 words). Never for nav, headings, table headers |
| T10 | Group title (card/drawer/sheet) = 16px semibold |
| T11 | Overlay title (dialog/modal) = 18px semibold |
| T14 | Title inside slot has margin: 0 — slot padding manages spacing |
| T20 | Font ≤12px (--font-size-xs) MUST use font-weight ≥ medium for legibility |
Content writing: Sentence case everywhere, action-oriented labels ("Save changes" not "OK"), no blame, max 2 lines for error messages.
§7. Accessibility — WCAG 2.2 AA
📖 Full rules: references/domains-typography-a11y-responsive.md §7
| ID | Critical Rule |
|---|---|
| F1 | Focus ring uses var(--ring) token, never hide outline |
| F2 | Focus/tab order matches visual order |
| F3 | Modal focus trap + Escape close |
| F7 | Focused element never obscured by sticky elements |
ARIA patterns: Button, Dialog, Tab Panel, Alert/Toast, Menu, Switch, Progress, Tooltip — each with required roles/attributes in reference file.
§8. Responsive & Multi-Platform
📖 Full rules: references/domains-typography-a11y-responsive.md §8
Breakpoints: 320px (Mobile S) → 375px (Mobile L) → 768px (Tablet) → 1024px (Desktop) → 1440px+ (Wide)
| ID | Critical Rule |
|---|---|
| R2 | No horizontal scroll at any breakpoint |
| R3 | Touch targets ≥44×44px on mobile, spacing ≥8px |
| R4 | Viewport meta tag required |
DS density integration: Instead of only media queries, switch data-style-mode attribute (compact/default/comfortable/spacious) to auto-scale all tokens.
§9. Motion & Micro-interaction
📖 Full rules: references/domains-motion-errors-governance.md §9
Duration scale: Micro (50-100ms) → Fast (100-200ms) → Medium (200-400ms) → Slow (400-700ms)
| ID | Critical Rule |
|---|---|
| M1 | Always respect prefers-reduced-motion — disable non-essential animations |
| M2 | Animate only transform + opacity. Never animate width/height/top/left |
| M3 | Duration/easing use DS tokens, never hardcode |
| M7 | Only loading spinners may use infinite animation |
§10. Error Handling & System States
📖 Full rules: references/domains-motion-errors-governance.md §10
7 system states every page/component must handle: Ideal, Loading, Empty, Error, Partial, Offline, Permission
| ID | Critical Rule |
|---|---|
| E1 | Error message = What happened + Why + How to fix |
| E3 | Every error has ≥1 action (Retry, Go back, Contact support) |
| E4 | Form errors inline below field, never alert() |
| E5 | Errors never clear user input |
| E6 | Error identified by text + icon, never color alone |
§11. UX Governance & Documentation
📖 Full rules: references/domains-motion-errors-governance.md §11
Decision documentation: Context → Decision → Alternatives → References → Impact
Component doc standard (9 sections): Overview, Anatomy, States, Variants, Interactions, Accessibility, Content Guidelines, Code Usage, Do/Don't
Review process: PROPOSE → REVIEW → APPROVE → IMPLEMENT → VALIDATE → SHIP
UX Debt severity: 🔴 Critical (fix immediately) → 🟡 Major (fix in sprint) → 🟢 Minor (backlog)
UX → Token Quick Lookup
Mục đích: Agent PHẢI dùng bảng này để chọn token ĐÚNG cho từng UX tier. KHÔNG chọn token theo tên cảm tính. LUÔN cross-check actual px value.
Typography Tokens
| UX Tier (§6.1) | Size Range | Correct Token | Actual px | ❌ KHÔNG dùng |
|---|---|---|---|---|
| Display | 36-57px | --text-style-heading-1-* |
30px | — |
| Headline | 24-32px | --font-size-2xl to --font-size-4xl |
24-36px | — |
| Title (Group) | 16px | --font-size-base |
16px | --font-size-sm (14px, quá nhỏ) |
| Title (Overlay) | 18px | --font-size-lg |
18px | --font-size-base (16px, quá nhỏ) |
| Body | 14-16px | --font-size-sm to --font-size-base |
14-16px | --font-size-xs (12px, quá nhỏ) |
| Label | 12-14px | --font-size-xs to --font-size-sm |
12-14px | --font-size-2xs (10px, quá nhỏ) |
| Caption | 11-12px | --font-size-xs |
12px | --font-size-2xs (10px < 11px min!) |
⚠️
--font-size-2xs= 10px → DƯỚI NGƯỠNG Caption 11px → KHÔNG BAO GIỜ dùng cho text hiển thị. Chỉ OK cho badge count, tag số nhỏ (non-essential info).
Line-height Tokens (T3)
| UX Tier | Ratio | Token |
|---|---|---|
| Display/Heading | 1.1-1.2 | --font-leading-tight |
| Title | 1.2-1.3 | --font-leading-snug |
| Body | 1.5-1.75 | --font-leading-normal to --font-leading-relaxed |
| Label | 1.3-1.4 | --font-leading-snug |
| Caption | 1.4-1.5 | --font-leading-normal |
Spacing Tokens (S2: 4px grid)
| Purpose | Token | px | S2 compliant? |
|---|---|---|---|
| Related items gap | --spacing-1 |
4px | ✅ |
| Section gap in group | --spacing-3 to --spacing-4 |
12-16px | ✅ |
| Between groups | --spacing-4 to --spacing-6 |
16-24px | ✅ |
❌ --spacing-0-5 |
--spacing-0-5 |
2px | ❌ NOT 4px grid |
❌ --spacing-px |
--spacing-px |
1px | ❌ NOT 4px grid |
⚠️
--spacing-0-5(2px) và--spacing-px(1px) vi phạm S2 (4px base unit). Chỉ OK cho: border-width, outline-offset, decorative micro-adjustments.
Anti-patterns (Quick Reference)
| ❌ Anti-pattern | ✅ Correct | Domain |
|---|---|---|
| Color alone for status | Color + icon + text | §1 + §7 |
| No loading state | Skeleton/spinner for >1s | §10 |
| Hardcode px/rem | Use spacing tokens | §4 |
| No focus ring | var(--ring) on all interactive |
§7 |
| Width/height animation | Transform + opacity only | §9 |
| Alert() for errors | Inline error message | §10 |
| Inconsistent nav placement | Fixed across pages | §3 |
| "Error occurred" (vague) | What + Why + How to fix | §10 |
| Button label "OK" | Action verb: "Save changes" | §6 |
| No reduced-motion fallback | @media (prefers-reduced-motion) |
§9 |
| Skip heading levels (h1 → h3) | h1 → h2 → h3 in order | §6 + §7 |
| Infinite non-loading animation | Only spinners may loop | §9 |
| Blame user in errors | "We couldn't save" | §10 |
| Missing empty state | Illustration + CTA + explanation | §10 |
| Tab order ≠ visual order | DOM order = visual order | §7 |
| btn-lg for every button | Default = .btn (md), btn-lg only for CTA |
§5 |
| Mixed button sizes in action group | Same size for all buttons in group | §5 |
| Card buttons left, dialog buttons right | Use flex-end for all web action groups (AG-1) |
§5 |
| No action-group layout on mobile | Use .action-group--responsive for stacked full-width |
§5 |
| Breadcrumb on mobile app | Web only — mobile dùng back button + section title (N9) | §3 |
Audit Framework
Scoring Matrix
| # | Domain | Weight | Score (0-10) |
|---|---|---|---|
| §1 | Visual Hierarchy & Color | 10% | /10 |
| §2 | Interaction Principles | 12% | /10 |
| §3 | Navigation & IA | 8% | /10 |
| §4 | Layout & Spacing | 10% | /10 |
| §5 | Component Behavior | 12% | /10 |
| §6 | Typography & Content | 8% | /10 |
| §7 | Accessibility (A11y) | 15% | /10 |
| §8 | Responsive & Multi-Platform | 10% | /10 |
| §9 | Motion & Micro-interaction | 5% | /10 |
| §10 | Error Handling & States | 5% | /10 |
| §11 | Governance & Documentation | 5% | /10 |
| TOTAL | 100% |
Grade Scale
| Grade | Score | Meaning |
|---|---|---|
| A+ | 9.5-10 | World-class — MD3/HIG parity |
| A | 8.5-9.4 | Enterprise-grade — production-ready |
| B | 7.0-8.4 | Good — minor gaps, ship with known issues |
| C | 5.0-6.9 | Needs work — significant UX debt |
| D | 3.0-4.9 | Poor — requires major overhaul |
| F | < 3.0 | Failing — not suitable for production |
Audit Workflow
1. RUN automated checks first:
node design-system/scripts/pipeline/run-pipeline.js --only=3,4,6 # review + verify + audit
2. MANUAL audit each domain — read the reference file for the domain's checklist
3. SCORE each domain (0-10) and calculate weighted total
4. REPORT using the template in references/domains-motion-errors-governance.md §11Audit Report Template
## 🔬 UX Audit Report — {System/Component Name}
**Date**: YYYY-MM-DD | **Auditor**: Agent
**Scope**: {Full system / Component / Page}
**Grade**: {A+/A/B/C/D/F} ({score}/10)
### Executive Summary
{1-2 paragraph overview}
### Domain Scores
| Domain | Score | Key Findings |
|--------|:-----:|-------------|
| §1 Visual | /10 | {summary} |
| ... | ... | ... |
### Critical Issues (🔴)
1. {Issue} — Rule {ID} violated → **Fix**: {how}
### Major Issues (🟡)
1. {Issue} — Rule {ID} → **Fix**: {how}
### Minor Issues (🟢)
1. {Issue}
### Recommendations
1. {Priority 1}
2. {Priority 2}