UX Heuristics Review skill for Claude Code

A review is done when every finding is tied to a specific screen and task step, names the heuristic it violates, carries a severity with a reason, and proposes a fix concrete enough to build. A list of opinions (“feels cluttered”) with no task, evidence, or fix is not a review.

Ground rules

• Evaluate tasks, not screens. Pick the 3–5 tasks that matter most and walk them step by step as a first-time user, then as a frequent user.
• Evidence for every finding: screenshot or element reference, the step, and what the user would see or do.
• Separate observation from recommendation. Write what happens, then why it is a problem, then the fix.
• Rate severity independently of effort to fix; report effort separately.
• A heuristic review finds likely problems; it does not replace testing with real users. Say so in the report and recommend tests for the highest-uncertainty findings.
• Also note what works, briefly, so the team does not “fix” good patterns.

Workflow

- [ ] 1. Scope: product, users, key tasks, platform, constraints
- [ ] 2. Gather the material (live app, build, screenshots, Figma, code)
- [ ] 3. Walk each task end to end; log raw observations
- [ ] 4. Map observations to heuristics; merge duplicates
- [ ] 5. Rate severity and estimate effort
- [ ] 6. Write fixes; group into quick wins vs. structural work
- [ ] 7. Deliver the report in the output format

1. Scope

Product: <name, platform>
Primary users: <role, expertise, frequency of use>
Key tasks: 1. Sign up and create first project  2. Invite a teammate  3. Export a report
Out of scope: <billing, admin settings>
Material reviewed: <URL/build/Figma link, date>

If tasks are not given, infer them from the navigation and the product’s core promise, and state the assumption.

3. Walk the tasks

For each step record: what the user is trying to do, what the UI shows, what they must know or remember, what could go wrong, and how they recover. Also exercise:

• Empty account state, first-run, and returning-user state.
• Errors: invalid input, network failure, permission denied, timeouts.
• Keyboard-only path and 200% zoom (overlaps with accessibility; flag and hand off deep issues to accessibility-audit).
• Mobile width if the product supports it.

4. The 10 heuristics (quick probes)

#	Heuristic	Probe questions
H1	Visibility of system status	Does every action get feedback within 100ms? Is progress shown for waits > 1s? Is the current location (nav, step) clear?
H2	Match with the real world	Are labels in the user’s words, not internal or database terms? Are icons conventional?
H3	User control and freedom	Can users undo, cancel, go back, and exit flows without losing work?
H4	Consistency and standards	Same action, same name and place everywhere? Platform conventions followed?
H5	Error prevention	Are destructive actions confirmed or undoable? Do constraints prevent invalid input before submit?
H6	Recognition rather than recall	Are options visible? Does the user have to remember values from a previous screen?
H7	Flexibility and efficiency	Shortcuts, bulk actions, defaults, saved views for frequent users?
H8	Aesthetic and minimalist design	Does every element earn its place? Is the primary action visually dominant?
H9	Help users recognize, diagnose, recover from errors	Do errors say what happened, why, and how to fix, next to the problem?
H10	Help and documentation	Is contextual help available where people get stuck, searchable and task-oriented?

For the detailed checklist per heuristic with common violations, read references/heuristics-checklist.md when a task walk feels clean but the experience is still poor, or for a formal audit.

5. Severity scale (Nielsen 0–4)

Rating	Meaning	Typical signal
4 Catastrophic	Blocks task completion or causes data loss	Users cannot finish signup; delete without confirm or undo
3 Major	Causes significant delay, errors, or abandonment; high priority	Key action hidden in an overflow menu; error message with no fix
2 Minor	Slows users or causes confusion; recoverable	Inconsistent labels; missing loading feedback on a short wait
1 Cosmetic	Polish; fix if time allows	Misaligned icons, uneven spacing
0	Not a usability problem	Disagreement on taste

Weigh three factors and write the reason: frequency (how many users hit it), impact (how hard to overcome), persistence (one-time or every time).

Effort: S (copy/CSS, < 1 day), M (component change, days), L (flow or IA change).

6. Writing fixes

• Specific: “Move ‘Invite teammate’ from Settings > Members to the project header as a secondary button; keep the Settings entry” beats “Make invite more discoverable”.
• Reuse existing patterns in the product before inventing new ones.
• When the fix is uncertain, propose a test (5-user usability test, A/B, first-click test) instead of a redesign.

Common high-severity patterns

• Destructive action without confirmation or undo (H3, H5): prefer undo toasts for reversible actions; typed confirmation only for irreversible, high-impact ones.
• Form loses input on validation error or back navigation (H3, H5).
• Silent failures: an action appears to succeed but did not (H1, H9).
• Primary action visually equal to secondary or destructive actions (H8, H5).
• Internal jargon in navigation (“Entities”, “Workspaces v2”) (H2).
• Multi-step flows with no progress indicator or save state (H1, H3).
• Required information only discoverable from documentation (H6, H10).

Gotchas

• Reviewing the happy path only misses most severe issues; errors and empty states are where products break.
• Expert blindness: if you know the product, deliberately do the task without using knowledge the UI does not provide.
• Inflated severity everywhere makes the report useless; typically fewer than 20% of findings should be 3 or 4.
• Do not recommend adding tooltips to fix unclear labels; fix the label.

Verification

• Every finding has: ID, task step, heuristic(s), severity with reason, evidence, fix, effort.
• Duplicates merged (one root issue appearing on 5 screens is one finding with 5 locations).
• Top findings re-checked against the live product or latest design before delivery.
• Severity distribution sanity-checked; positives section included.

Output contract

# UX heuristic review: <product> — <date>

## Summary
Scope: tasks 1–3 on web app build 2026-10-12. 18 findings: 1 catastrophic, 4 major,
9 minor, 4 cosmetic. Biggest risk: <one sentence>.

## Top 5 fixes (by severity, then effort)
1. [F-03] ...

## Findings
### F-03 Deleting a project has no confirmation or undo
- Task / step: Task 3, step 2 (Project settings > Delete)
- Heuristics: H3 User control, H5 Error prevention
- Severity: 4 — irreversible data loss, button sits next to "Rename" (high frequency of
  mis-click), affects every project owner
- Evidence: screenshot settings-delete.png; button is 32px tall, 8px from Rename
- Fix: Move Delete to a separate "Danger zone" section; require typing the project name;
  soft-delete with 30-day restore
- Effort: M

## What works well
- ...

## Recommended user tests
- First-click test on the dashboard to validate F-07 navigation changes