tkersey/ux-audit

<!-- TOC: Core | Prompt | Quick Check | Heuristics | CLI | Output | Anti-Patterns | References -->

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