domains / design / ux-audit / ux-audit

ux-audit

Skill card

combined

The two copies define different procedures for the same skill name. The first is an interaction-first live walkthrough that requires an Interaction Manifest, hard gates (console/network/a11y/perf), and a verdict state machine. The second is a static screen audit based on Nielsen's heuristics and mobile UX checklists, with a letter-grade output. Neither is a reproduction of the other, and crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

# UX Audit

## When to Use
Use this skill to audit a live web app or mobile screens for usability issues. Choose the mode that matches the task:
- **Live Walkthrough** for a running app where interaction is possible.
- **Static Screen Audit** for design files, screenshots, or code without a running instance.

## Mode 1: Live Walkthrough (Interaction-First)

### Verdict States
The audit ends in exactly one of:
- **Pass** — Critical = 0, High = 0, all hard gates green, Interaction Manifest complete.
- **Conditional Pass** — Critical = 0, High = 0, all hard gates green, but Medium/Low present.
- **Fail** — at least one Critical or High finding, OR a hard gate red.
- **Incomplete** — Interaction Manifest missing required entries, a phase wasn't run, OR the audit-the-audit meta-check fires. Not legal to upgrade to Pass even if everything observed looked fine.

### Hard Gates
These auto-fail the audit. They cannot be downgraded.

| Gate | Threshold | Severity if violated |
|------|-----------|----------------------|
| Console errors during walkthrough | > 0 | Critical |
| Console warnings during walkthrough | > 0 | High |
| Network 5xx | > 0 | Critical |
| Network 403 / 404 on authenticated pages | > 0 | High |
| Layout collapse at any tested viewport / pane combo | > 0 | High |
| axe-core Critical violations on any audited page | > 0 | Critical |
| axe-core Serious violations on any audited page | > 0 | High |
| LCP on representative route | > 4.0s | High |
| CLS on representative route | > 0.25 | High |
| INP on representative route | > 500ms | High |
| Required Interaction Manifest entry missing | n/a | Incomplete |
| Manifest median gap between entries < 0.5s | n/a | Incomplete |

### Phases (in order)
1. **Pre-flight** — Persona Lock, browser tool, URL, viewport, capability tests.
2. **Discovery** — sitemap, thread inventory, element inventory.
3. **Walkthrough** — Interaction Manifest, threads, element exhaustion, multi-pane stress, first-time-user lens, live interaction smoke.
4. **Polish** — visual polish sweep, component perfection checklist.
5. **Stress** — scenario battery (11 scenarios) + extended stress recipes.
6. **Verdict** — verdict state, hard-gate scorecard, perfection roadmap, findings with reproduction.
7. **Fix-and-verify** — patch findings, re-walk affected slices, update report.

### Persona Lock
Source the persona in this order:
1. **Argument** — if the user provided one.
2. **Project personas** — read existing persona files.
3. **Ask once** — "Who uses this app and what are they trying to get done?"

Capture: role, tech comfort, time pressure, emotional state, device context. Lock the persona by writing the chosen persona at the top of the audit report.

## Mode 2: Static Screen Audit (Nielsen's Heuristics)

### Nielsen's 10 Usability Heuristics
1. **Visibility of System Status** — Loading states, success/error feedback, progress indicators, active navigation state, real-time data timestamps.
2. **Match Between System and Real World** — User language, recognizable icons, locale-appropriate number/date formats.
3. **User Control and Freedom** — Back navigation, confirmation for destructive actions, undo, dismissible modals, no dark patterns.
4. **Consistency and Standards** — Same action = same appearance, consistent color meanings, text hierarchy, consistent card styling, spacing grid.
5. **Error Prevention** — Visually distinct destructive buttons, validation on blur, explicit confirmation for dangerous actions, visible input constraints.
6. **Recognition Rather Than Recall** — Labels on icons, visible current state, recent/frequent items, placeholder text showing format.
7. **Flexibility and Efficiency** — Key actions within 3 taps, pull-to-refresh, touch targets >= 44x44px, frequent actions in easy-to-reach zones.
8. **Aesthetic and Minimalist Design** — One primary task per screen, no decorative clutter, information pyramid, max-4-items card density, one hero metric per page.
9. **Help Users Recover from Errors** — Plain-language error messages, fix suggestions, partial failure isolation, retry buttons, field-specific form errors.
10. **Help and Documentation** — Empty states guide action, onboarding for first-time features, tooltips for complex metrics.

### Mobile-Specific UX Checks
- **Touch & Gesture** — Touch targets >= 44x44px, >= 8px between targets, no hover-dependent interactions, visible swipe affordances.
- **Performance Perception** — Skeleton screens within 300ms, optimistic updates, above-the-fold first, no layout shift.
- **Safe Areas** — Content not hidden behind notch/Dynamic Island, bottom content not behind home indicator, BottomNav safe padding.

### Dark Pattern Prevention
- No forced bottom sheets on entry.
- No exit-prevention dialogs.
- Every screen has a way to go back/dismiss.
- CTA labels clearly describe the action.
- No manipulative graphics.

## Output Format

### For Live Walkthrough
1. **Verdict State** — Pass, Conditional Pass, Fail, or Incomplete.
2. **Hard-Gate Scorecard** — Table of gate results.
3. **Findings** — Each with reproduction steps, evidence path, and suspected code location.
4. **Perfection Roadmap** — Prioritized list of improvements.

### For Static Screen Audit
1. **Score** — A+ to F rating with breakdown.
2. **Critical Issues** — Must fix (blocks usability).
3. **Major Issues** — Should fix (degrades experience).
4. **Minor Issues** — Nice to fix (polish).
5. **Recommendations** — Specific code changes for each issue.

## Conflicts
- **jezweb/claude-skills** requires live interaction and an Interaction Manifest; a static sweep cannot produce a verdict.
- **sickn33/agentic-awesome-skills** audits screens using Nielsen's heuristics and mobile UX checklists; does not require live interaction or an Interaction Manifest.
- **jezweb/claude-skills** uses a verdict state machine (Pass/Conditional Pass/Fail/Incomplete) based on hard gates.
- **sickn33/agentic-awesome-skills** uses an A+ to F score with Critical/Major/Minor issues.