ux-audit

name	ux-audit
description	Systematic UX evaluation using Nielsen heuristics and accessibility checks. Use when reviewing UI, "is this usable", improving user experience, or pre-launch.

UX Audit

Core Insight: Users don't read manuals. If it's not obvious, it's broken.

THE EXACT PROMPT

Conduct a UX audit of this [application/CLI/interface]:

1. Nielsen's 10 Usability Heuristics
2. Accessibility basics (keyboard, contrast, screen reader)
3. User flow analysis (happy path + error paths)
4. Cognitive load assessment

Produce prioritized report:
- Critical (blocking)
- Important (degraded experience)
- Suggestions (polish)

Include file:line references and concrete fixes.

---

Quick Check (5 min)

| Area | Status | Notes |
|------|--------|-------|
| Navigation | 🟢/🟡/🔴 | |
| Forms | 🟢/🟡/🔴 | |
| Errors | 🟢/🟡/🔴 | |
| Accessibility | 🟢/🟡/🔴 | |
| Mobile/Responsive | 🟢/🟡/🔴 | |

---

Nielsen's 10 Heuristics (Quick Reference)

#	Heuristic	Key Question
1	Visibility	Does user know what's happening?
2	Real World	Familiar language & concepts?
3	Control	Can user undo/escape?
4	Consistency	Same action = same result?
5	Error Prevention	Prevents mistakes before they happen?
6	Recognition	Options visible vs. memorized?
7	Flexibility	Shortcuts for experts?
8	Minimal	Visual clutter removed?
9	Error Help	Error messages helpful?
10	Documentation	Help available when needed?

Deep dive: HEURISTICS.md

---

CLI-Specific Heuristics

Heuristic	CLI Application
Visibility	--verbose, progress bars, spinners
Real world	Standard flags (--help, --version)
Control	Ctrl+C works, --dry-run available
Consistency	-v short, --verbose long
Error prevention	Confirmation prompts, --force
Recognition	--help shows all options
Flexibility	Short + long flags, piping
Minimal	Clean default, verbose optional
Error help	Actionable messages, suggested fixes
Documentation	--help, man pages, examples

Generate checklist: ./scripts/generate-checklist.py cli

---

Accessibility Quick Check

The Big 4

• Keyboard: All interactive elements reachable via Tab?
• Contrast: Text 4.5:1 ratio minimum?
• Not color-only: Icons/patterns, not just color?
• Screen reader: Labels, alt text, ARIA?

Deep dive: A11Y.md

---

Output Template

# UX Audit: [Project]

## Summary
**Score:** X/10 | **Critical:** N | **Important:** N | **Suggestions:** N

## Critical Issues (Must Fix)
### 1. [Title]
**Heuristic:** #N - [Name]
**Location:** `file:line`
**Problem:** [What's wrong]
**Fix:** [Specific solution]

## Important Issues (Should Fix)
[Same format]

## Suggestions
- [ ] [Item]

## Heuristic Scores
| Heuristic | Score |
|-----------|-------|
| 1. Visibility | X/10 |
...

Full template: EXAMPLES.md

---

Audit Depth

Type	Time	When
Quick Scan	5-10 min	PR review, spot check
Standard	30-60 min	Pre-release, feature review
Deep Audit	2+ hr	Major redesign, compliance

---

Anti-Patterns

Don't	Do
"It's intuitive"	Test with fresh eyes
Ignore error paths	Audit happy AND error flows
Skip accessibility	Check the Big 4 minimum
Vague issues	Specific file:line + fix
All issues equal	Prioritize by impact

---

Integration

With Hooks

Auto-run a11y check after UI edits:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$TOOL_INPUT_PATH\" | grep -qE '\\.(tsx|jsx|html)$'; then npx axe \"$TOOL_INPUT_PATH\" 2>/dev/null || true; fi"
      }]
    }]
  }
}

With Other Skills

Combine with...	For...
multi-model-triangulation	Multiple UX perspectives
multi-pass-bug-hunting	Include UX issues in sweeps
ui-polish	After fixing critical UX issues

---

References

Topic	File
Full heuristic details	HEURISTICS.md
Accessibility deep dive	A11Y.md
Example audits	EXAMPLES.md

Scripts

Script	Purpose
scripts/generate-checklist.py	Generate project-specific checklist

./scripts/generate-checklist.py web    # Web app
./scripts/generate-checklist.py cli    # CLI tool
./scripts/generate-checklist.py mobile # Mobile app
./scripts/generate-checklist.py api    # API/DX