SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsux-audit

ux-audit

Frontend & websites

View repository

Updated 10-15 15:31

About this skill

UX Audit

Static UX-quality reviewer for React/Next.js code. Operates at the feature level (a checkout flow, an onboarding flow, a dashboard) — not the principle level. Answers one question for a frontend dev with a PR open: "which of these will hurt users in production, and which are nice-to-haves?"

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

Defer to the right tool. Do not duplicate what these already do well:

Concern Use this tool instead Why
Core Web Vitals (LCP, CLS, INP) Lighthouse + web-vitals + Vercel Agent Field + lab measurement, not static
WCAG rule violations axe-core / jsx-a11y Authoritative rule list, structured violations
a11y prevention at write time eslint-plugin-jsx-a11y Lint catches before runtime
Visual regression Chromatic / Percy Pixel-level diffs
Bundle size budget size-limit / bundle-analyzer Continuous budget tracking
Generic bug review CodeRabbit / Vercel Agent LLM bug review of the whole diff

When a finding overlaps any of the above, link out — don't restate.

See references/defer-to-other-tools.md for the full inventory.

Audit Workflow

Copy and track this checklist:

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
  33 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

Default scope is the PR diff. Detect with:

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

Audit only those files. Surface the base branch in the output: Auditing: 8 files changed vs main.

For a quick local check (single component): git diff --name-only HEAD -- src/Component.tsx.

For a full sweep: explicit --full src/ (rare; only when introducing the skill to a codebase).

Ship-readiness verdict

Every audit emits a top-level verdict before per-finding details:

═══════════════════════════════════════════════════════════
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
═══════════════════════════════════════════════════════════

Verdict tiers:

  • ✅ 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

Three formats, all rendered from the same JSON. Pick based on context.

Adapter When Format
Terminal table Local dev, fast scan Tight 5-col table grouped by surface
PR comment GitHub / Vercel review Markdown with suggestion blocks for inline diffs
CI JSON Pipelines, dashboards Strict JSON per references/output-schema.md

See references/output-adapters.md for verbatim templates and field mappings.

Skip protocol

A finding can be intentionally suppressed with an inline comment:

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

Slug must match the rule slug. Suppressions are reported in the audit summary so reviewers can verify intent.

Reference Files

File Read when
references/feature-playbooks.md Step 2-3 — detecting features and selecting their playbooks
references/modern-failure-modes.md Index of all 33 modern rules grouped by category
references/states-coverage.md Validating loading/empty/error/disabled coverage per component type
references/ship-readiness.md Step 5 — assigning each finding a ship tier with examples
references/output-adapters.md Step 6 — formatting findings for terminal / PR comment / JSON
references/defer-to-other-tools.md Recognizing concerns to delegate (CWV, WCAG, bundle, etc.)
references/output-schema.md Strict JSON schema for findings + verdict
references/observational-rubrics.md Layer 3 rubric rules (1-5 scoring with anchors)
rules-modern/<category>-<slug>.md Step 4 — running a Layer 2 modern frontend check
rules-modern/_sections.md Category index for the modern rule layer
rules/<prefix>-<slug>.md Step 4 — running a Layer 3 Laws of UX check
rules/_sections.md Category index for the Laws of UX rule layer

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

Self-flag the audit as INCOMPLETE if any of these are true:

  • 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)