UX Audit

What this skill IS

• A diff-aware reviewer that audits changed files in a PR
• A feature-level checklist runner: detects "this is a sign-in flow" / "this is a checkout" / "this is a modal" and runs the right playbook
• A ship-readiness verdict generator: every finding gets

  release-blocker | fix-this-sprint | backlog

• A concrete-fix advisor that uses modern React 19 APIs (

  useActionState

  ,

  useFormStatus

  ,

  useOptimistic

  ,

  useTransition

  ,

  <Suspense>

  , error boundaries)

What this skill IS NOT

references/defer-to-other-tools.md

Audit Workflow

UX Audit progress:
- [ ] Step 1: Determine scope (PR diff via `git diff --name-only main` OR explicit file/folder)
- [ ] Step 2: Detect features in scope (sign-in / checkout / form / modal / list / dashboard / etc.)
- [ ] Step 3: For each feature, run its playbook from references/feature-playbooks.md
- [ ] Step 4: For each check, load the matching rule (rules-modern/ for state/form/focus bugs; rules/ for Laws of UX)
- [ ] Step 5: Assign each finding a ship tier per references/ship-readiness.md
- [ ] Step 6: Group findings by surface, render with the chosen output adapter
- [ ] Step 7: Verify the audit-self-check before reporting

1. Scope. Default to

   git diff --name-only main

   if in a git repo with uncommitted changes; otherwise audit the explicit scope the user passes. Don't audit the whole codebase by default — noise floor is too high.
2. Detect features. Match on element semantics + filenames + route paths. A

   <form>

   with email + password = sign-in. A

   <form>

   with a multi-step indicator = onboarding. A

   role="dialog"

   = modal. See

   references/feature-playbooks.md

   for detection heuristics per feature.
3. Run playbook. Each feature has 5-7 ordered checks. Don't skip checks even when you expect them to pass; each pass goes into the audit-self-check.
4. Load rules. Two layers:

   • rules-modern/

     (Layer 2) — modern frontend UX failure modes (state coverage, form preservation, focus mgmt, optimistic rollback, CLS, microcopy). This is where most findings come from.

   • rules/

     (Layer 3) — Laws of UX (Hick's, Fitts's, Miller's, etc.). Used for cognitive/perceptual reasoning when Layer 2 doesn't apply.
5. Ship tier. Every finding gets one of three tiers (see

   references/ship-readiness.md

   ):

   • release-blocker

     — fix before merge (data loss, broken auth, missing critical-path error state, dark patterns, focus traps that don't restore)

   • fix-this-sprint

     — merge but log issue (sub-44 px target on touch, missing skeleton, vague error, missing empty CTA)

   • backlog

     — track, ship (dark-mode untested, RTL not verified, microcopy nits)
6. Group + render. Group by surface (component file or page). Render with one of the three adapters in

   references/output-adapters.md

   .
7. Self-check. Verify the audit was actually run (rules executed > rules planned, file:line cited on every finding, fix snippet on every finding).

Three audit layers

Layer 1 — Feature playbooks  (the entry point)
  references/feature-playbooks.md
  12 features × 5-7 ordered checks → pulls rules from Layers 2 and 3

Layer 2 — Modern frontend failure modes  (the high-leverage layer)
  rules-modern/<category>-<slug>.md
  30 rules covering state coverage, form preservation, focus mgmt,
  async/optimistic, CLS pairings, microcopy, dark mode, i18n, mobile.
  Detection recipes use React 19 APIs.

Layer 3 — Laws of UX  (the cognitive/perceptual reserve)
  rules/<prefix>-<slug>.md
  30 rules for Hick's, Fitts's, Miller's, etc. Invoked when feature
  playbooks need cognitive load / decision / perception reasoning.
  Usually 1-2 of these per audit; not all 30.

Diff-aware mode

git diff --name-only main -- '*.tsx' '*.jsx' '*.ts' '*.js' '*.css' '*.module.css'

Auditing: 8 files changed vs main

git diff --name-only HEAD -- src/Component.tsx

--full src/

Ship-readiness verdict

═══════════════════════════════════════════════════════════
SHIP VERDICT: ❌ NOT READY (1 release-blocker)

Surface count:           3 (CheckoutForm, PaymentStep, ConfirmStep)
Findings:                7
  Release blockers:      1   ⛔  Form data loss on validation (PaymentStep.tsx:42)
  Fix this sprint:       3   ⚠️
  Backlog:               3   📋

Defer-to (not audited here):
  Performance (CWV):     Run Lighthouse
  Bundle size:           Run size-limit
  WCAG violations:       Run axe-core
═══════════════════════════════════════════════════════════

• ✅ READY — 0 release-blockers, ≤3 fix-this-sprint
• ⚠️ READY WITH FOLLOW-UP — 0 release-blockers, ≥4 fix-this-sprint
• ❌ NOT READY — ≥1 release-blocker
• 🚫 INCOMPLETE — audit-self-check failed (re-run)

Output adapters

suggestion

references/output-schema.md

references/output-adapters.md

Skip protocol

{/* ux-audit-ignore:focus-not-restored — intentional: parent owns focus */}
<Dialog open={open} onClose={onClose}>

Reference Files

references/feature-playbooks.md

references/modern-failure-modes.md

references/states-coverage.md

references/ship-readiness.md

references/output-adapters.md

references/defer-to-other-tools.md

references/output-schema.md

references/observational-rubrics.md

rules-modern/<category>-<slug>.md

rules-modern/_sections.md

rules/<prefix>-<slug>.md

rules/_sections.md

Gotchas

• Don't audit the whole codebase by default. Diff-aware mode is the default; full sweeps are explicit.
• Don't duplicate other tools. If a finding is "LCP > 4s," that's Lighthouse — link, don't restate. If it's "missing alt text," that's axe — link, don't restate.
• Don't skip the feature-detection step. Running every rule against every file produces noise; running the right playbook per feature produces signal.
• Don't assign every finding

  release-blocker

  . Reserve that tier for genuine ship-blockers (data loss, broken critical path, dark patterns). Inflation kills the signal.
• Don't suggest fixes without modern React APIs when applicable. "Add a loading state" is weak; "Wrap in

  <Suspense fallback={<Skeleton />}>

  and use

  useTransition

  for the trigger" is actionable.
• Don't render markdown without a JSON pass first. Even when the user wants markdown, build the JSON document first to keep findings auditable across runs.
• Don't pile on Laws of UX findings. Layer 3 is reserve. If a finding has both a Layer-2 framing ("missing error state") and a Layer-3 framing ("Postel's Law violation"), use Layer 2 — it's more specific and actionable.
• Don't quote the source verbatim. Every rule paraphrases; lawsofux.com uses CC BY-NC-SA which would contaminate the skill.
• Don't fabricate detections. If you can't grep the file or see the JSX, mark the finding

  unknown

  with a reason. Never claim a finding without evidence.

Audit-self-check

INCOMPLETE

• Fewer rules ran than the playbook's planned count
• More than 30% of rules returned

  unknown

  (insufficient evidence)
• No

  file:line

  cited on any fail/warn finding
• No

  reproduceSteps

  or

  fix

  snippet provided
• Median apparent time-per-rule was implausibly short (no Read or Grep tool calls between findings)
• Every finding ended up in the same tier (suspect: blanket-assignment without judgment)