ux-audit

name	ux-audit
description	Heuristic usability and accessibility audit of existing web pages — load a rendered page, evaluate it against Nielsen's 10 usability heuristics + WCAG 2.2 (A/AA) + responsive behavior + the page's own goal, and return prioritized findings with a concrete fix for each. Use whenever the task is to review, audit, critique, or "find usability/UX problems" on one or more web pages, do an accessibility (a11y) check, assess responsiveness, or propose usability fixes — even if the user just says "is this page any good", "what's wrong with this UI", "make this more usable", or hands you a URL/screenshot. This is a review/audit method, not a design-decision debate (that's design-council) and not functional testing (that's webapp-testing). Read by the ux-auditor agent, which renders each page with a browser driver and fans out one auditor per page.
license	MIT

UX Audit

Audit an existing, rendered page against a fixed rubric and return findings the caller can act on. The discipline that makes this useful: audit what's actually on screen, cite the heuristic or success criterion, and propose a concrete fix. A finding with no location and no fix is noise; a "problem" you assumed without observing the page is worse.

This is distinct from neighbours:

• design-council deliberates one high-stakes design decision (preserves dissent). Use it for "should we restructure this flow?", not "audit these 12 pages."
• webapp-testing checks that features work. UX audit checks whether they're usable and accessible even when they work.

Inputs you need

• The page(s): a URL, a local file, or a running dev server. For a series of pages, the ux-auditor agent fans out — one auditor per page (see that agent).
• The page's goal — what is the user there to do? You can't judge usability without it. If not given, infer it from the page and state your assumption in the finding set.
• Viewports to check (at least one mobile ~375px and one desktop ~1280px). Responsive problems only show up if you actually resize.

Render the page first — don't audit blind

Audit the rendered DOM and the visual result, not the raw source. Use whatever browser driver is installed (prefer agent-browser, fall back to playwright-cli; the CLI binary is playwright-cli, not playwright):

# preference order — use whichever exists
if command -v agent-browser >/dev/null 2>&1; then echo agent-browser
elif command -v playwright-cli >/dev/null 2>&1; then echo playwright-cli
else echo NONE; fi

For each page capture: a screenshot at each viewport, the rendered HTML/DOM, and (where the driver allows) computed styles for contrast and a tab-order walk for keyboard checks. The screenshot is your evidence; reference it in findings.

Isolate the session — the #1 cause of bad audits under fan-out. Both drivers default to a single shared browser session via a background daemon. When several audits run at once (the fan-out pattern), they collide on that shared session and you get cross-contamination — evals returning another page's DOM. Always give each audit its own named session and close it when done. This, not the tool, is what broke an early run of this skill.

Time-box the driver. If it still doesn't render cleanly within a few tries, switch drivers or drop to a static audit and say so — don't sink 30 calls into fighting it.

agent-browser recipe (preferred — handles local files and concurrency cleanly)

S="uxaudit-$$"                                  # unique session per audit (fan-out safe)
agent-browser --session "$S" --allow-file-access open "file:///abs/path/page.html"
agent-browser --session "$S" --allow-file-access open "https://example.com"   # remote too

• Local files load directly with --allow-file-access — no HTTP server needed.
• eval via --stdin avoids all shell-quoting corruption (the trap that wastes calls); return a string with JSON.stringify(...):

  agent-browser --session "$S" eval --stdin <<'EOF'
  JSON.stringify((() => {
    const noAlt = Array.from(document.images).filter(i => !i.alt).length;
    const p = document.querySelector("p"); const s = getComputedStyle(p);
    const b = document.querySelector("button"); const r = b.getBoundingClientRect();
    return { noAlt, color: s.color, bg: s.backgroundColor, target: r.width + "x" + r.height };
  })())
  EOF
  

• Evidence & viewports: snapshot -i (a11y refs/roles), screenshot --annotate (numbered labels — ideal for icon-only buttons), screenshot --full. For mobile, set viewport via config/flags or audit at the iOS profile (-p ios).
• Always agent-browser --session "$S" close when done.

playwright-cli recipe (fallback — binary is playwright-cli, not playwright)

• Serve local files over HTTP — file:// URLs often don't load. Start a throwaway server and target http://localhost:

  ( cd "$DIR" && python3 -m http.server 8731 & )      # or `uv run python -m http.server`
  playwright-cli open                                  # start the browser
  playwright-cli goto "http://localhost:8731/page.html"  # goto, not open-with-arg
  

  open <url> may stay on about:blank; always goto explicitly after open.
• eval takes a function and the value prints under ### Result. Use () => ... form; a bare expression containing => is misparsed as a function-to-apply. Return a string (JSON.stringify(...)) so the result is unambiguous:

  playwright-cli eval "() => { const b=document.querySelector('button'); const r=b.getBoundingClientRect(); return JSON.stringify({w:r.width,h:r.height}); }"
  

• High-yield evals: images missing alt, inputs whose .labels is empty, computed color/backgroundColor for contrast, getBoundingClientRect() for target size.
• Viewports & evidence: playwright-cli resize 375 812 then screenshot, repeat at 1280 900. playwright-cli snapshot dumps the accessibility tree (names/roles).
• Always playwright-cli close when done.

If no driver is installed (or you abandoned a flaky one), set "driver": "static-only", audit the static HTML + any screenshot the user provides, and flag in notes that dynamic/contrast/keyboard/viewport checks were not performed. An honest partial audit beats a guess.

The rubric

Walk all three lenses. Don't stop at accessibility — usability and responsiveness catch different failures.

1. Nielsen's 10 usability heuristics

1. Visibility of system status — does the UI show what's happening (loading, saved, selected, where-am-I)?
2. Match with the real world — language/concepts the user knows, not system jargon.
3. User control & freedom — undo, cancel, back, clear exits from unwanted states.
4. Consistency & standards — same thing looks/acts the same; platform conventions.
5. Error prevention — constraints, confirmations, sensible defaults that stop mistakes.
6. Recognition over recall — options visible; don't make users remember across steps.
7. Flexibility & efficiency — accelerators for experts without blocking novices.
8. Aesthetic & minimalist design — no competing clutter; signal over noise.
9. Help users recover from errors — plain-language errors that say what and how to fix.
10. Help & documentation — findable, task-oriented help where needed.

2. WCAG 2.2 — target Level A & AA

Check the high-yield criteria first:

• Text alternatives — meaningful alt on informative images; empty alt="" on decorative ones.
• Contrast (1.4.3 / 1.4.11) — text ≥ 4.5:1 (≥ 3:1 for large text ≥ 18.66px bold / 24px); UI components & graphics ≥ 3:1. Measure from computed colours, don't eyeball.
• Keyboard (2.1.1) & focus visible (2.4.7) — everything operable by keyboard; a visible focus indicator; logical tab order; no keyboard traps.
• Labels & names (1.3.1 / 4.1.2) — form controls have associated <label>s; controls expose an accessible name; ARIA used correctly (or not at all).
• Headings & structure (1.3.1 / 2.4.6) — one logical heading outline; landmarks (main, nav, header); descriptive page <title>.
• Target size (2.5.8, new in 2.2) — interactive targets ≥ 24×24 CSS px (or spaced).
• Resize/reflow (1.4.10) — usable at 320px width / 400% zoom without horizontal scroll.
• Don't rely on colour alone (1.4.1) — state shown by more than hue.

3. Responsive & device behaviour

• Layout holds at mobile (~375px) and desktop (~1280px); no overflow, overlap, or cut-off controls. Tap targets aren't cramped. Content reflows rather than requiring zoom/scroll.

Severity — so the caller can triage

Match the fleet's review scale (same as code-reviewer):

• blocking — users can't complete the page's goal, or a WCAG Level A failure shuts out a group (e.g. unlabeled critical control, keyboard trap, no alt on the only CTA icon).
• major — serious friction or a WCAG AA failure (contrast below 4.5:1, focus not visible, confusing error with no recovery).
• minor — polish: inconsistency, clutter, small-but-real friction.

Reserve blocking for "this stops someone," and back every finding with what you observed.

Return format (final message) — JSON only

One object per audited page. (When fanned out, the agent merges these.)

{
  "page": "url-or-path",
  "goal": "what the user is here to do (stated or inferred)",
  "viewports_checked": ["375x812", "1280x900"],
  "driver": "agent-browser | playwright-cli | static-only",
  "summary": { "blocking": 0, "major": 0, "minor": 0 },
  "findings": [
    {
      "severity": "blocking | major | minor",
      "lens": "usability | accessibility | responsive",
      "ref": "Nielsen #5 | WCAG 1.4.3 | responsive@375px",
      "location": "selector or region, e.g. 'form#signup > button.submit'",
      "evidence": "what you observed (+ screenshot ref / measured value)",
      "suggested_fix": "concrete change to make",
      "confidence": "high | medium | low"
    }
  ],
  "notes": "assumptions, what couldn't be checked, empty if none"
}

Be precise over exhaustive. Ten located, fixable findings beat forty vague ones. If you couldn't render the page, say what you could and couldn't assess rather than inventing problems.

Privacy

The audited pages and any findings about a specific product are often the client's property — keep the page content and results out of any shared/committed location. This skill and the ux-auditor agent are generic and publishable; the data they process is not.