# UX Audit

Walk through a live web app AS a real user to find usability + behavioural bugs that...

- Repository: https://github.com/jezweb/claude-skills (1094 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jezweb/claude-skills --skill ux-audit -g -a claude-code -y`
Codex: `npx skills add jezweb/claude-skills --skill ux-audit -g -a codex -y`
Cursor: `npx skills add jezweb/claude-skills --skill ux-audit -g -a cursor -y`
Gemini CLI: `npx skills add jezweb/claude-skills --skill ux-audit -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jezweb/claude-skills`

## Description

Walk through a live web app AS a real user to find usability + behavioural bugs that static reviews miss. REQUIRES proof of interaction (typing, clicking, sending, observing) before any verdict, a sweep that didn't interact terminates with verdict 'Incomplete'. Walks threads, exercises every element, runs the multi-pane stress matrix, visual polish sweep, component perfection checklist, automated a11y (axe-core), pragmatic performance budget (LCP/CLS/INP), scenario battery (11 scenarios), and stress recipes including the real-flavour data battery. Hard gates: console errors/warnings = 0, network 5xx = 0, layout collapse = 0, axe Critical/Serious = 0, perf budget green. Audit-the-audit meta-check rejects rushed reports. Each finding has reproduction steps, evidence path, and suspected code location. Trigger with 'ux audit', 'walkthrough', 'qa sweep', 'audit the app', 'dogfood this', 'check all pages', 'find what's broken', 'stress the UI'.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# UX Audit

Walk through a live web app AS a real user. The audit is **interaction-first**, typing, clicking, sending, watching, screenshotting. A static DOM sweep cannot produce a verdict.

## 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 (manifest timestamps clustered < 0.5s apart, screenshots fewer than 2 × routes, console reads fewer than 1 × routes, Phase 3 took < 1m for an exhaustive audit). Not legal to upgrade to Pass even if everything observed looked fine.

If the work doesn't include a complete Interaction Manifest, the only legal verdict is **Incomplete**. "It looked OK" is not Pass. A clean Pass with implausible timings is rejected, the agent must redo the audit with real interaction.

## 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 (pragmatic budget) | > 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 (didn't actually interact) |

The rest: https://github.com/jezweb/claude-skills/blob/HEAD/plugins/dev-tools/skills/ux-audit/SKILL.md