| name | ux-heuristics |
| description | Evaluate a UI against Nielsen's 10 Usability Heuristics — score each heuristic, flag violations with severity ratings, and produce a prioritized fix list. Use when the user asks for a "UX review", "usability audit", "heuristic evaluation", or "why is this UI confusing to users". Do NOT use for code quality or accessibility — use output-enforcement or accessibility-audit for those.
|
| origin | yamtam |
| version | 1.0.0 |
| compatibility | Any UI — web, mobile, desktop. Works from code, screenshot, or description. |
When to Use
- Use when: user says "why is this confusing", "users keep making mistakes", "UX review"
- Use when: reviewing a design before user testing
- Use when: diagnosing a specific UX complaint ("users can't find X")
- Do NOT use for visual aesthetics — use
ui-redesign or design-taste-frontend
- Do NOT use for accessibility compliance — use
accessibility-audit
The 10 Heuristics
H1 — Visibility of System Status
The system always keeps users informed about what is going on.
Check for:
- Loading states present on async operations
- Progress indicators for multi-step processes
- Clear feedback after actions (success/error messages)
- Active states on navigation items
H2 — Match Between System and Real World
The system speaks the users' language.
Check for:
- Technical jargon used where plain language would work
- Icons whose meaning is not universally understood (no tooltips)
- Dates, numbers, currencies in non-user locale format
- Metaphors that don't match user mental models
H3 — User Control and Freedom
Users can undo mistakes and exit unwanted states.
Check for:
- No undo/cancel on destructive actions
- No way to exit a flow mid-way
- Modals/dialogs with no close option
- Back button behavior inconsistent with user expectation
H4 — Consistency and Standards
Users should not have to wonder whether different words, situations, or actions mean the same thing.
Check for:
- Same action labeled differently in different places
- Similar UI elements that behave differently
- Platform conventions broken (right-click, swipe, keyboard shortcuts)
- Inconsistent button placement across screens
H5 — Error Prevention
Design carefully to prevent problems from occurring.
Check for:
- Forms allow invalid input with no real-time validation
- Destructive actions with no confirmation step
- Ambiguous options that users might misclick
- No constraints on inputs that have known valid ranges
H6 — Recognition Rather than Recall
Minimize the user's memory load.
Check for:
- Actions or options only available from memory (no visible affordances)
- Form fields don't show what format is expected
- No breadcrumbs or context indicators in complex flows
- Commands that must be remembered rather than recognized
H7 — Flexibility and Efficiency of Use
Accelerators for expert users, not at the expense of novices.
Check for:
- No keyboard shortcuts for power users
- Repetitive tasks with no shortcut or bulk action
- Advanced options completely hidden from everyone (not just collapsed)
- No way to customize frequent workflows
H8 — Aesthetic and Minimalist Design
Dialogues should not contain irrelevant or rarely needed information.
Check for:
- Every visible element serves a purpose or an action
- Information hierarchy unclear — secondary info competes with primary
- Marketing copy in UI flow (task completion ≠ marketing moment)
- Visual noise that dilutes important content
H9 — Help Users Recognize, Diagnose, and Recover from Errors
Error messages should be expressed in plain language, precisely indicate the problem, and constructively suggest a solution.
Check for:
- Error messages that say what went wrong but not how to fix it
- Error codes shown without human explanation
- Errors that disappear before the user can read them
- Form errors not linked to the specific field that caused them
H10 — Help and Documentation
Even though it is better if the system can be used without documentation, it may be necessary.
Check for:
- Complex features with no help text or tooltip
- Empty states with no guidance on what to do
- Onboarding that assumes prior knowledge
- Help content that requires leaving the current task
Severity Scale
Score each violation 0–4:
| Score | Label | Meaning |
|---|
| 0 | Not a problem | Can be ignored |
| 1 | Cosmetic | Fix only if time permits |
| 2 | Minor | Low priority |
| 3 | Major | High priority — fix before ship |
| 4 | Catastrophic | Must fix — blocks usability |
How It Works
- Read or view the UI — code, screenshot, or description
- Evaluate each of the 10 heuristics — one by one, no skipping
- Record violations with severity 1–4 (severity 0 = skip)
- Sort by severity — 4 first, then 3, then 2, then 1
- Produce fix list — specific, actionable, one fix per violation
Output Format
## UX Heuristics Evaluation
H1 — Visibility of System Status PASS
H2 — Match Between System and World VIOLATION (severity 2)
Issue: "Submit" button on invoice form — users unfamiliar with accounting
don't know if this sends or just saves.
Fix: Rename to "Send Invoice" — makes action explicit.
H3 — User Control and Freedom VIOLATION (severity 4)
Issue: No way to cancel a payment once "Confirm" is clicked.
Fix: Add 30-second undo window with toast notification.
...
## Summary
Violations: 6 (1× severity-4, 2× severity-3, 2× severity-2, 1× severity-1)
Must fix before ship: H3 (catastrophic), H9 (major), H1 (major)
Gotchas
- H8 (minimalist design) is about information density, not visual aesthetics — a visually busy UI can pass H8 if every element serves a purpose
- Evaluate from the user's perspective, not the developer's — "it's obvious" is not evidence
- A single screen may have violations of multiple heuristics simultaneously
- Severity 4 must block delivery — do not report it and move on
Anti-Fake-Pass Rules
Before claiming the evaluation is done, you MUST show:
Reference: gates/anti-fake-pass-gate.md
