ux-audit

Name: ux-audit
Author: jezweb

2.0kinstalls96forks

How to install ux-audit?

jezweb/claude-skills/ux-audit

$npx -y skills add jezweb/claude-skills --skill ux-audit

Installs into the current project.

Summary

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, ex

Files · 1

View on GitHub

SKILL.md

1	# UX Audit
2
3	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.
4
5	## Verdict states
6
7	The audit ends in exactly one of:
8
9	- Pass — Critical = 0, High = 0, all hard gates green, Interaction Manifest complete.
10	- Conditional Pass — Critical = 0, High = 0, all hard gates green, but Medium/Low present.
11	- Fail — at least one Critical or High finding, OR a hard gate red.
12	- 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.
13
14	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.
15
16	## Hard gates
17
18	These auto-fail the audit. They cannot be downgraded.
19
20	\| Gate \| Threshold \| Severity if violated \|
21	\|------\|-----------\|----------------------\|
22	\| Console errors during walkthrough \| > 0 \| Critical \|
23	\| Console warnings during walkthrough \| > 0 \| High \|
24	\| Network 5xx \| > 0 \| Critical \|
25	\| Network 403 / 404 on authenticated pages \| > 0 \| High \|
26	\| Layout collapse at any tested viewport / pane combo \| > 0 \| High \|
27	\| axe-core Critical violations on any audited page \| > 0 \| Critical \|
28	\| axe-core Serious violations on any audited page \| > 0 \| High \|
29	\| LCP on representative route (pragmatic budget) \| > 4.0s \| High \|
30	\| CLS on representative route \| > 0.25 \| High \|
31	\| INP on representative route \| > 500ms \| High \|
32	\| Required Interaction Manifest entry missing \| n/a \| Incomplete \|
33	\| Manifest median gap between entries < 0.5s \| n/a \| Incomplete (didn't actually interact) \|
34
35	A console warning is High minimum. A 5xx is Critical automatically. There is no "Medium console error" — that category does not exist in this skill.
36
37	axe-core thresholds are run per page (>1 violation on any single page fails). Performance thresholds are run once on a representative route (per-page is overkill); pragmatic budget is well above broken, well below CWV-strict. Full thresholds + rationale in [references/performance-budget.md](references/performance-budget.md). Full a11y wiring + severity mapping in [references/a11y-automation.md](references/a11y-automation.md).
38
39	### Allowlist for known noise
40
41	Some apps have known-noisy console / network categories that aren't bugs (Sentry info logs, browser-extension chatter, expected 401 on auth-check probes). Read the audit-config file before Phase 3 and apply its allowlist. Path fallback: `.jez/audit-config.yml` → `audit-config.yml` → `.audit/config.yml`. Allowlisted entries stay in the Interaction Manifest but suppress from findings. Verdict block shows both raw and allowlisted: `Console warnings: 3 (1 allowlisted, 2 reportable)`.
42
43	Default without a config: every console error / warning is a finding. Format, semantics, surface overrides in [references/audit-config.md](references/audit-config.md).
44
45	## Phases (in order)
46
47	1. Pre-flight — Persona Lock, browser tool, URL, viewport, capability tests
48	2. Discovery — sitemap, thread inventory, element inventory
49	3. Walkthrough — Interaction Manifest, threads, element exhaustion, multi-pane stress, first-time-user lens, live interaction smoke
50	4. Polish — visual polish sweep, component perfection checklist
51	5. Stress — scenario battery (11 scenarios) + extended stress recipes
52	6. Verdict — verdict state, hard-gate scorecard, perfection roadmap, findings with reproduction
53	7. Fix-and-verify — patch findings, re-walk affected slices, update report
54
55	For a 30-second pre-deploy check, use the dogfood drill at the bottom of this file — a p

People who liked this also viewed

6 picks

Type

ux-audit

2.0kinstalls96forks

View on GitHub

How to install ux-audit?

jezweb/claude-skills/ux-audit

$npx -y skills add jezweb/claude-skills --skill ux-audit

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# UX Audit
2
3	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.
4
5	## Verdict states
6
7	The audit ends in exactly one of:
8
9	- Pass — Critical = 0, High = 0, all hard gates green, Interaction Manifest complete.
10	- Conditional Pass — Critical = 0, High = 0, all hard gates green, but Medium/Low present.
11	- Fail — at least one Critical or High finding, OR a hard gate red.
12	- 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.
13
14	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.
15
16	## Hard gates
17
18	These auto-fail the audit. They cannot be downgraded.
19
20	\| Gate \| Threshold \| Severity if violated \|
21	\|------\|-----------\|----------------------\|
22	\| Console errors during walkthrough \| > 0 \| Critical \|
23	\| Console warnings during walkthrough \| > 0 \| High \|
24	\| Network 5xx \| > 0 \| Critical \|
25	\| Network 403 / 404 on authenticated pages \| > 0 \| High \|
26	\| Layout collapse at any tested viewport / pane combo \| > 0 \| High \|
27	\| axe-core Critical violations on any audited page \| > 0 \| Critical \|
28	\| axe-core Serious violations on any audited page \| > 0 \| High \|
29	\| LCP on representative route (pragmatic budget) \| > 4.0s \| High \|
30	\| CLS on representative route \| > 0.25 \| High \|
31	\| INP on representative route \| > 500ms \| High \|
32	\| Required Interaction Manifest entry missing \| n/a \| Incomplete \|
33	\| Manifest median gap between entries < 0.5s \| n/a \| Incomplete (didn't actually interact) \|
34
35	A console warning is High minimum. A 5xx is Critical automatically. There is no "Medium console error" — that category does not exist in this skill.
36
37	axe-core thresholds are run per page (>1 violation on any single page fails). Performance thresholds are run once on a representative route (per-page is overkill); pragmatic budget is well above broken, well below CWV-strict. Full thresholds + rationale in [references/performance-budget.md](references/performance-budget.md). Full a11y wiring + severity mapping in [references/a11y-automation.md](references/a11y-automation.md).
38
39	### Allowlist for known noise
40
41	Some apps have known-noisy console / network categories that aren't bugs (Sentry info logs, browser-extension chatter, expected 401 on auth-check probes). Read the audit-config file before Phase 3 and apply its allowlist. Path fallback: `.jez/audit-config.yml` → `audit-config.yml` → `.audit/config.yml`. Allowlisted entries stay in the Interaction Manifest but suppress from findings. Verdict block shows both raw and allowlisted: `Console warnings: 3 (1 allowlisted, 2 reportable)`.
42
43	Default without a config: every console error / warning is a finding. Format, semantics, surface overrides in [references/audit-config.md](references/audit-config.md).
44
45	## Phases (in order)
46
47	1. Pre-flight — Persona Lock, browser tool, URL, viewport, capability tests
48	2. Discovery — sitemap, thread inventory, element inventory
49	3. Walkthrough — Interaction Manifest, threads, element exhaustion, multi-pane stress, first-time-user lens, live interaction smoke
50	4. Polish — visual polish sweep, component perfection checklist
51	5. Stress — scenario battery (11 scenarios) + extended stress recipes
52	6. Verdict — verdict state, hard-gate scorecard, perfection roadmap, findings with reproduction
53	7. Fix-and-verify — patch findings, re-walk affected slices, update report
54
55	For a 30-second pre-deploy check, use the dogfood drill at the bottom of this file — a p

People who liked this also viewed

6 picks

Type