Skip to content

jezweb/claude-skills / plugins/dev-tools/skills/ux-audit

ux-audit

Verified

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'.

references/a11y-automation.md

View on GitHub
# Automated Accessibility (axe-core)

Manual keyboard-only walks (Scenario 5) catch focus traps and tab-order problems. They miss roughly 80% of structural a11y bugs — heading skips, contrast at hover/focus state, missing aria-labels, dynamic-content announcements, role mismatches. axe-core covers that 80% in <1 second per page.

This is **mandatory in Phase 4 (Polish)** for every audited page.

## The protocol

For every page audited:

1. Navigate to the page.
2. Inject axe-core (single CDN script tag).
3. Run `axe.run()` in the browser context.
4. Capture violations array.
5. Map severity → audit severity (table below) and log findings.

```js
// In the browser eval / playwright-cli / chrome MCP
await page.evaluate(async () => {
  // Inject axe-core if not present
  if (!window.axe) {
    await new Promise((resolve, reject) => {
      const s = document.createElement('script')
      s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.0/axe.min.js'
      s.onload = resolve
      s.onerror = reject
      document.head.appendChild(s)
    })
  }
  const results = await window.axe.run()
  return {
    violations: results.violations.map(v => ({
      id: v.id,
      impact: v.impact,
      description: v.description,
      help: v.help,
      helpUrl: v.helpUrl,
      nodes: v.nodes.length,
      sample: v.nodes[0]?.html?.substring(0, 200),
    })),
    incomplete: results.incomplete.length,
    passes: results.passes.length,
  }
})
```

## Severity mapping

axe reports `impact` per violation. Map to audit severity:

| axe `impact` | Audit severity | Hard-gate? |
|---|---|---|
| `critical` | Critical | YES — audit auto-fails |
| `serious` | High | YES — audit auto-fails |
| `moderate` | Medium | No — finding, not gate |
| `minor` | Low | No — finding, not gate |

## Hard-gate threshold

Add to the SKILL.md hard gates table:

| Gate | Threshold | Severity if violated |
|---|---|---|
| axe-core Critical violations | > 0 | Critical |
| axe-core Serious violations | > 0 | High |

A page with > 0 axe Critical or > 0 axe Serious cannot pass the audit. axe Moderate / Minor accumulate as Medium / Low findings respectively.

## Allowlist for known-noise

Some axe rules fire on intentional design choices that aren't real bugs (e.g. `landmark-one-main` on a chrome-less embed page, `region` on a wrapper that intentionally has no landmark). Allowlist via `.jez/audit-config.yml`:

```yaml
axe:
  ignore_rules:
    - landmark-one-main   # iframe-style embed pages
    - region              # legacy wrapper, refactor scheduled 2026-Q3
  ignore_pages:
    - /dashboard/components  # builder-mode, intentional
    - /dashboard/style-guide # builder-mode, intentional
```

Default with no config: every axe Critical / Serious is a finding. Allowlist is opt-in.

## Findings format

Each axe violation becomes a finding in the report:

```
ID: H-N
Layer: Visual / Interaction (a11y)
Severity: High (axe Serious)
Surface: /dashboard/inbox

axe rule: color-contrast
  Description: Elements must have sufficient color contrast (WCAG AA: 4.5:1 normal, 3:1 large)
  Help: https://dequeuniversity.com/rules/axe/4.10/color-contrast
  Nodes affected: 3
  Sample: <button class="btn-secondary">Mark all read</button>
    Computed contrast: 3.2:1 (text-muted-foreground on bg-muted)
    Required: 4.5:1

Reproduce:
  1. Navigate to /dashboard/inbox
  2. Inspect "Mark all read" button (or any .btn-secondary)
  3. Read computed colour ratios in DevTools

Suspected location: src/components/ui/button.tsx — secondary variant; or the
  --muted-foreground token in src/styles/globals.css
Suggested fix: bump --muted-foreground from oklch(0.55 0 0) to oklch(0.45 0 0)
  or change secondary variant to use --foreground.
```

## What axe doesn't catch

axe is structural. It misses:

- Whether the screen-reader announcement actually conveys meaning
- Whether dynamic content (toasts, live updates) announces to AT
- Whether keyboard tab-order makes sense (axe checks focusability, not order quality)
- Whether copy is comprehensible to assistive tech users

Those still require Scenario 5 (Keyboard Only) + manual screen-reader testing for high-stakes apps. Don't drop those in favour of axe — combine.

## Run once per page

Don't loop axe per element. One `axe.run()` per page, after the page has settled (wait for `networkidle` or 1.5s). Re-run after major state changes (modal opened, drawer expanded) since aria attributes shift.

For a 16-route audit, total axe runtime is ~16 seconds. Cheap.

## Skipping pages

For builder-mode reference pages (Components, Style guide), axe is overkill — the page exists to display every component variant including disabled / error / contrast-test states that intentionally fail strict rules. Add to `ignore_pages` in the audit config.

For genuinely user-facing pages, no skipping. Even auth pages (sign-in, sign-up) audit cleanly.

## Companion: keyboard-only manual sweep

axe + Scenario 5 (Keyboard Only) is the right pair. axe catches the structural 80%; Scenario 5 catches the experiential 20% (tab order quality, focus visibility under custom themes, escape-key behaviour, focus trap in modals).

If you only have time for one, do axe (more bugs per minute). If the app is high-stakes (legal/medical/finance), do both.

**Last Updated**: 2026-04-30
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall