ux-audit

name

ux-audit

description

Audit any UI against established UX, usability, and accessibility frameworks and return severity-scored, heuristic-cited findings plus a coding-agent fix-plan. Works on a screenshot, a set of screens, a Figma export, or a live app at a URL/localhost (driven with agent-browser). Use whenever someone asks to "audit this UI", "review my design", "UX review", "usability review", "accessibility audit", "critique this screen", "is this confusing", "why is this hard to use", "find UX problems", or shares a screenshot/URL and wants design feedback — even if they don't say the word "audit". Prefer this over generic freeform design opinions: the whole point is to evaluate against named, cited frameworks rather than vibes.

UX Audit

Evaluate a UI against a library of named, cited frameworks — not gut feel. The single most important idea (from the practitioners who pioneered this): AI feedback is only as good as what you evaluate it against. A request for "feedback on this screen" produces mush. A request that checks the screen against Nielsen #1, Fitts's Law, the FTU test, and WCAG contrast produces findings you can act on and defend.

This skill turns a screenshot, a flow, a Figma export, or a live app into: severity-scored findings, each citing the specific heuristic it violates, plus a ranked fix-plan a coding agent can execute.

When each mode applies

• Static mode — the user attaches/points at one or more images (screenshots, Figma exports). Audit the pixels you can see. This is the default and works for mockups and early wireframes too.
• Live mode — the user gives a URL or localhost address. Drive the running app with agent-browser to capture real screens, walk journeys, and inspect live state (focus rings, error recovery, disabled states) that a static image can't show. See scripts/live_capture.sh.

If both an image and a URL are offered, prefer live mode and use the image as reference.

The workflow

Work through these steps in order, tracking each one explicitly so you don't skip context-setting — the classification and assumptions in steps 1–2 are what make the findings sharp instead of generic.

1. Set context (do NOT skip)

Before judging anything, establish what you're judging and for whom. Findings mean nothing without this.

• Classify the profile: mobile-app, web-app, or marketing-site (or other with a one-line rationale). Load the matching file from references/profiles/ — it modulates which criteria matter (a marketing site is judged on conversion and trust; a web-app on task completion and cognitive load).
• Name the target user and their primary task ("a first-time user trying to publish their first post"). If the user hasn't told you, infer from the screen and state your assumption explicitly — then audit against it. If you genuinely can't tell, ask one question.
• Calibrate severity to maturity. A rough wireframe should not be flagged for polish. If it's clearly early-stage, say so and focus on structural issues, not pixel-nudging.

2. Capture (live mode only)

If auditing a live app, follow scripts/live_capture.sh:

• Auto-generate 3–6 realistic journeys from what the app appears to do (e.g. sign-up, empty-state → first value, a destructive action, error recovery).
• For each journey, agent-browser open → walk the steps → screenshot each screen → snapshot (accessibility tree) for structure. Capture live states static images miss: :focus rings, disabled buttons, validation errors, loading/empty states.
• Note the actual flow, not just end screens — half of UX lives in the transitions.
• Safety: never actually execute a consequential action against a real system. When a journey reaches a destructive, financial, or publish/send step (delete, pay, send-to-all, go-live), stop at the confirmation/preview and audit that — do not confirm. Only carry a high-stakes action through to completion if the user has explicitly pointed you at a throwaway test/staging environment where it's safe. Auditing must not cause the damage it's checking for.

3. Audit against the frameworks

Run every applicable lens. Read the reference files as you need them — don't try to hold all of them in your head:

• references/frameworks.md — the core heuristic library: Nielsen's 10, Shneiderman's 8 Golden Rules, Gerhardt-Powals, the behavioral laws (Hick, Fitts, Miller, Jakob, Peak-end), Fogg Behavior Model, Cialdini, Gestalt, Norman, Tognazzini. One line per heuristic so you can cite precisely.
• references/custom-checks.md — three checklists that catch what generic heuristics miss: FTU (first-time-user survivability), TRUST (safety at high-stakes moments), COG (cognitive load). Run all three on every audit — they flag the recurring problems most reliably.
• references/accessibility.md — WCAG 2.2 AA quick-reference: contrast, target size, focus visibility, labels, motion.
• references/ai-slop.md — the generic-design detector: purple gradients, emoji-as-icons, placeholder copy, centered-everything, default shadcn with no identity. Flag these — they read as unfinished and untrustworthy.
• references/content-heuristics.md — copy and content design: clarity, labels, CTAs, error messages, empty-state instruction, tone.
• references/patterns/ — component pattern library. When the UI contains a recognizable component, load its file and check the screen against that concrete, cited checklist — this is where general principles become specific "this sidebar / form / table is wrong here" findings. Available: sidebar-navigation.md, forms.md, tables-data-density.md, modals-dialogs.md, buttons-actions.md, empty-states.md. Load only the ones present on the screen. (New patterns get added here over time; treat the list as growing, not fixed.)
• Live mode adds the journey lens: for each journey, score understand → decide → act → recover. Can the user comprehend the screen, make an informed choice, complete the task, and recover from mistakes? A break in any link is a finding.

Every finding must cite its source — and the citation must actually fit the claim. Not "this is confusing" but "the primary and secondary actions have equal visual weight, so nothing signals which is the safe default — Gestalt similarity (equal weight reads as equal priority), Norman signifiers (no cue marks the default), and custom check COG-2 (one obvious next step per screen)." Citation is what separates this from an opinion — but a citation stapled to an unrelated claim is worse than none: it launders an opinion as authority. If you can't name a heuristic that genuinely covers the problem, say so plainly rather than reaching for a famous name that doesn't apply.

4. Score and phrase each finding

• Severity, four levels:
  • 🔴 Critical — blocks task completion or accessibility; users will fail or get hurt (data loss, no error recovery, unreadable contrast).
  • 🟠 Major — significantly impairs usability; users struggle and some give up.
  • 🟡 Minor — noticeable friction; users succeed but annoyed.
  • 🔵 Cosmetic — polish; safe to defer.
• Phrase with ASK — Actionable, Specific, Kind. Say exactly what to change, point to the exact element, and stay constructive. The audit exists to make the product better, not to dunk on the designer.
• Always report what's working. Show 2–4 strengths. Context matters — a finding list with no strengths is untrustworthy and demoralizing, and it hides which good patterns to preserve during fixes.

5. Deliver

Produce the report using assets/report-template.md, then the fix-plan.

1. Markdown report — summary, context profile, findings by category (severity-ordered), a priority table (#, severity, category, finding, fix), 3–5 quick wins, and strengths to preserve.
2. fix-plan.md — the findings re-expressed as a ranked, actionable task list a coding agent can pick up: what to change, where (file/component if known from the codebase), and the acceptance check. This is what makes the audit flow straight into fixes when you're building in Claude Code.
3. Offer HTML export as a follow-up (not by default) — assets/report-template.md includes instructions for building a self-contained HTML export with embedded screenshots, for sharing with teammates or clients.

Principles

• Evaluate against named frameworks, always cite. The citation is the value.
• Context first, criticism second. Profile + target user + task, or the findings are noise.
• Match critique to maturity. Don't polish-nitpick a wireframe; don't wave through a shipped flow.
• Strengths alongside problems. Balance is credibility.
• The output should be executable, not just readable — someone (or an agent) should be able to act on it directly.