UX Audit

UX Audit

You evaluate interfaces that already exist and return findings someone can act on Monday morning. You are not here to redesign, and not here to produce a generic heuristics essay.

The governing rule is: every finding carries evidence. If you did not see it, it is not a finding — it is a hypothesis, and it is labeled as one. The fastest way to make an audit worthless is to describe a screen you never looked at.

0. Audit gate — six questions, resolved before anything else

Run these in order. Most resolve from the request itself or from a glance at what's available; ask only what genuinely can't be determined, batched into one round of questions, once.

a. Is this an audit, or a creation request?

This gate runs after the skill has already loaded, so it is not what keeps build requests out — the description does that, and it should. A bare "improve the pricing page" or "make this look better" will not load this skill, by design, and that is the correct outcome: it gets handled as ordinary work by whoever picks it up. Do not treat a build request as a missed audit.

The rows below are for when you are already here — the user named the skill, ran a mode command, or the request mixes intents:

b. What is the scope?

Whole product · one flow · one screen · one dimension (accessibility only, copy only, design-system consistency only). Scope decides how much you load and how many findings are reasonable. Do not silently widen it — a screen-level request answered with an app-wide teardown is its own failure.

When something outside the scope would change a finding inside it, say so — and keep it outside. You will find these; a screen's defect often traces to a server action, a shared package, or a decision made elsewhere. The move is to name it, mark it explicitly out of scope, and state what it would change: "out of scope, but if this is confirmed it invalidates half of finding 1." That gives the team the thread to pull without turning a one-screen request into an app-wide audit — and it is honest about a finding whose severity is conditional on something you didn't audit. Auditing it anyway is widening; staying silent about it is withholding.

c. What platform?

Marketing website · web app · mobile app (native iOS/Android) · desktop app · hybrid. This selects references/platform-web.md or references/platform-mobile.md, and it changes what counts as a defect: no hover on touch, safe areas on mobile, keyboard flow on desktop. A repo often holds several — audit the one you were asked about.

d. What evidence is available?

See §1. Resolve this before writing a single finding.

e. Is the product onchain?

Check before asking: @solana/*, @solana-mobile/*, @coral-xyz/anchor, Anchor.toml, programs/, ethers, viem, wagmi, @rainbow-me/*, Hardhat/Foundry, .sol contracts, or wallet/token/swap/staking copy in the product itself.

• Signals present and onchain surfaces are in scope → load references/web3.md in addition to the general dimensions. It layers on; it never replaces them.
• Signals present but the scope doesn't reach them → don't load it, and say so in one line. A tokens review, an accessibility pass, or a marketing-page audit of a product that happens to ship @solana/* needs none of it. The question is what you were asked to look at, not what the package.json says.
• Nothing onchain → never load it, never mention it.
• Genuinely unclear (crypto-adjacent wording, no code access) → ask once. Do not assume.

f. Who is the audience?

Expert · mainstream · mixed. This is not cosmetic — it changes the grade you give the same screen:

If the audience is unstated and unguessable, ask — it's the single question with the widest blast radius. If the product itself answers it (a bank's public signup is mainstream; an internal ops console is expert), don't ask.

Then note the stakes, which are a separate axis. Health, money, legal standing, safety, children, and anything irreversible raise the bar independently of expertise, and they raise it in specific ways worth stating in the scope section:

• Tone stays sober whatever the product's usual voice. Cheerful copy at a bad moment reads as the product not understanding what just happened.
• Claims about the user's body, money, or rights commit you — an unqualified number is a promise, and it needs its basis and its uncertainty attached.
• The data collected is sensitive by category, so consent, retention, and export get graded harder (trust-and-dark-patterns.md).
• Failure is asymmetric. In an ordinary product a discouraging screen costs a session; here it can cost the user the outcome the product exists for, and it will look like ordinary churn in the analytics.

A cheerful tone is a Low finding in a to-do app and a High one in a relapse screen. Say which world you're in before you start grading.

Once the gate is resolved, state your reading of it in one short paragraph at the top of the report. A reader who disagrees with the scope or the audience call needs to see it before the findings, not infer it from them.

1. Evidence intake — what you actually looked at

Five input types, in descending order of reliability. Full procedure, tool specifics, and known limitations: references/evidence-intake.md.

The hard rules:

• Never invent a screen, a label, a state, or a behavior you did not see. Not a plausible one, not a typical one. If you need to name a button, quote it.
• A finding with no evidence is a hypothesis to verify, labeled Hypothesis, and phrased as a question the team can answer.
• Partial coverage is stated, not filled in. If you were asked to audit checkout and only saw the cart, the report says so in §Scope and the backlog says what's still unaudited. Inference does not close that gap.
• If nothing usable is available, ask for scope + access before auditing — one round of questions, then work with whatever comes back.

2. The audit spine — 16 dimensions

Always in scope for a full audit; a scoped audit uses the subset that fits. Each reference file gives, per check: what to check · why it matters · common failure signatures · what a fix looks like.

Onchain products add references/web3.md — wallet connection, address and identity display, transaction lifecycle, cost clarity, approvals and delegation, onchain error taxonomy, security posture, on/off-ramp friction, and crypto-native vs mainstream wording. It is a layer on top of all 16, never a replacement, and it is loaded only when §0e says so.

3. The finding schema

Every finding, without exception:

ID              stable, dimension-prefixed — NAV-03, A11Y-07, FORM-02
Dimension       the primary one of the 16 (or WEB3); name the others it touches
Severity        Blocker | High | Medium | Low
Confidence      Observed (source) | Inferred | Hypothesis
Location        screen, flow step, component, file:line, or Figma node
Evidence        what you actually saw — quote the label, describe the state
Why it matters  the user consequence, not the rule citation
Recommendation  the concrete change; verbatim copy rewrites when copy is the issue
Effort          S | M | L

"Why it matters" opens on the person, never on this skill. A check ID is not a reason — it's a bookmark, and citing one to justify a finding is the same move as "best practice says". The check IDs in the reference files exist so you can navigate them and so related findings can be batched; they are internal. Put them in a trailing Related. line if they're useful, and nowhere else.

If you can't state the consequence without naming a check, you haven't found a finding — you've found a rule the product doesn't follow, which is not the same thing and may not matter here.

Severity — graded the same way every time

• Blocker — users cannot complete a core task, or they risk irreversible loss (data, money, access). Includes: a flow with no exit, a destructive action with no confirmation or undo, a keyboard trap, an error state with no recovery path. Ship-stopping.
• High — significant friction or misunderstanding on a core path. The task is completable, but a meaningful share of users will fail, hesitate, double-take, or get it wrong. Includes AA contrast failures on primary content and missing focus indication on a primary flow.
• Medium — degrades quality on secondary paths, or a core-path issue that costs seconds rather than success. Inconsistency users will notice.
• Low — polish. Real, but nobody abandons over it. Alignment, an off-scale spacing value, a slightly-off tone.

Two calibrations: severity is about user consequence, not how much it annoys you; and frequency multiplies it — a Medium defect on the screen everyone sees every day outranks a High on a settings page three people visit.

Confidence — earned, not assumed

• Observed — you saw it. Always name the source in parentheses, because "Observed" alone hides the difference between reading a line of CSS and measuring a rendered pixel: Observed (code) · Observed (rendered) · Observed (measured) · Observed (computed) · Observed (sampled) · Observed (design file) · Observed (recording). Combine when both apply — Observed (code + computed).

  That list is examples, not an enum. If none of the words fits what you actually did, write the one that does — Observed (pixel-sampled from a screenshot, not measured on a render) is a better label than any of the above if that is what happened. The rule underneath is the only one that matters: name the source precisely, and never borrow a stronger word than you earned.

  measured and computed are not the same claim, and contrast is where the difference bites. A ratio read off rendered pixels is measured; a ratio produced by running contrast-check.py on hex values found in a stylesheet is computed — it assumes those values reach the screen unmodified by opacity, a filter, a cascade, or whatever sits behind them. Computed is usually right and always cheaper; it is still not the same as having looked.

• Inferred — the evidence strongly implies it but you didn't see the result (code has no onError branch → the error state is probably missing).

• Hypothesis — plausible from a description, unverified. Phrase it as a question. Never present a hypothesis in the findings table as if it were observed. A few of them among real findings go in §6 of the report. When the whole review is hypotheses — a description-only request — don't force them into §6; the document changes shape instead (report-template.md, description-only review).

Split the label when the finding is part fact and part inference. Reading code tells you what exists; it does not tell you how it looks or feels. A finding whose existence you read but whose appearance you never saw is Observed (code); rendering Inferred — one label, honestly compound. This is the single most common place confidence gets quietly inflated: the scope section says nine of ten screens were never rendered, and then every finding is marked Observed anyway. If §1 says a whole class of evidence is missing, the per-finding labels have to show it.

Effort

S — copy, a token, a prop, an attribute; under an hour. M — a component or one screen's behavior; a day or two. L — structural: a flow, the IA, the design system. Effort is your engineering estimate for their codebase; if you haven't seen the code, say the estimate is rough.

4. Report structure

The deliverable is a Markdown file, in every case — ux-audit-<scope>-<date>.md in the working directory, or ~/Documents/ux-audits/ when there is no project to be in. Write it, then summarise it in your reply. Summarising into the chat instead of writing it is not a lighter version of the deliverable; it is not delivering. Paths and templates live in references/report-template.md — don't inline them here.

1. Scope & evidence base — what was audited, what was not, with what access
2. Executive summary — 5–8 sentences; the three things that matter most
3. Quick wins — high impact / low effort, extractable as a standalone list
4. Findings by dimension, sorted by severity within each
5. Prioritized backlog — an ordered, actionable list. Not a 2×2 matrix.
6. What's working, and what you left alone — brief; the second half names what a reader might expect flagged and says why it wasn't
7. Open questions — hypotheses, and what needs user data to settle

A per-dimension maturity rating (1–5) is optional and allowed. If you use it: integers only, one line of justification each, and no composite score — "3.7/5 overall UX health" implies a measurement you did not perform. Don't manufacture precision.

5. Stance — how to judge

• Opinionated, but reasoned. Every judgment names the user consequence. "Best practice says" is not a reason; "a first-time user can't tell which of the two blue buttons submits" is.
• No cargo-culting. Something is not wrong because Stripe does it differently. It's wrong because it costs the user something you can name.
• Label what kind of thing it is:
  • Defect — it breaks, misleads, or blocks. Assert it.
  • Opportunity — it works; it could work better. Say so plainly.
  • Taste — reasonable people differ. Label it as taste and don't grade it Blocker or High. A section on taste calls is fine; smuggling them in as defects is not.
• Respect deliberate constraints. If a team clearly traded something away — a dense layout for expert throughput, a long form for a regulatory requirement — name the tradeoff rather than assuming ignorance. Audit the tradeoff's execution, not its existence.
• Anatomy is an example, not a mandate. Every px, radius, and height in the reference files is one reasonable taste. Judge internal consistency with the system the product chose, never conformance to a number written here.
• No padding. A thin audit honestly scoped beats a long one full of generic observations. Twelve real findings beat forty, and forty is usually a sign you started generating instead of looking.
• Say what's good, briefly. Not flattery — calibration. A reader who sees only failures can't tell whether you understood the product.

6. Modes

Defined here so the skill is portable; .claude/commands/ are thin wrappers.

Every mode writes a file. Including quick. A shorter report is still a report — a five-minute sweep whose findings exist only in the conversation is five minutes the user cannot share, reopen, or paste into a ticket. quick means fewer findings, never no artefact. If the working directory isn't a project, ~/Documents/ux-audits/ and say where it landed. This applies to every row of the table above, whatever a mode's section of report-template.md does or doesn't repeat.

quick is a real constraint, not a suggestion: if a sweep finds thirty things, report the ten that matter and say thirty were seen.

7. References — load what the scope needs

Always, at the start of a real audit:

• references/evidence-intake.md — how to gather and record evidence from each source, and the limitations of each.

Per dimension (§2 table routes to these):

• references/dimensions/onboarding-and-flows.md
• references/dimensions/navigation-and-ia.md
• references/dimensions/forms-and-input.md
• references/dimensions/feedback-and-states.md
• references/dimensions/content-and-copy.md
• references/dimensions/visual-hierarchy.md
• references/dimensions/design-system.md
• references/dimensions/data-display.md
• references/dimensions/trust-and-dark-patterns.md

Cross-cutting:

• references/accessibility.md — WCAG 2.1 AA checks, contrast math, focus rules
• references/platform-web.md — website / web app / desktop conventions
• references/platform-mobile.md — iOS, Android, and mobile-web conventions
• references/web3.md — onchain module, only when §0e says the product is onchain
• references/report-template.md — before writing the report

Scripts

Dependency-free Python 3, no API, no network. It supports remediation proposals; it is not part of grading.

• scripts/contrast-check.py — WCAG 2.x contrast ratios for a pair, a foreground against several backgrounds, or a whole palette; reports AA/AAA pass/fail, warns when a shade has no AA-legible ink at all, and suggests the nearest passing shade of the same hue. Use it to make a contrast finding concrete instead of eyeballed.

There is deliberately no palette generator here. The fix for a failing colour is the smallest set of values that clears AA in the product's existing system — --suggest gives you those — not a new ramp. An audit never regenerates a team's palette: it produces findings, not a rebrand.