UX/UI Audit

The rule that makes this worth reading

Every finding carries a measurement or a verbatim quote. No exceptions.

This matters more than it sounds. An audit full of "the hierarchy could be stronger" and "consider improving contrast" is indistinguishable from something generated without looking at the page, so a team learns to skim it. An audit that says "the focus ring is 1.6px solid rgb(0,75,254) on rgb(20,22,28) — 2.96:1, and SC 1.4.11 requires 3:1" gets fixed the same afternoon, because there is nothing left to argue about and nothing left to investigate.

When you cannot measure something, say so plainly. "I could not verify this" is a legitimate line in a report. A confident wrong finding costs the team a morning and costs you their trust in the other forty.

What the scripts catch, and what only you can catch

Run the probes first — they are fast, exhaustive and never get bored. But understand their ceiling, because it determines where you spend your attention.

Probes are good at structure. Contrast arithmetic, element geometry, ARIA wiring, href graphs, meta tags. Machine work, done perfectly.

Probes are blind to meaning. They cannot tell that a pricing page promises "live sessions with instructors" for a product that has no instructors, that a plan description still reads "traditional description for the premium plan", that the assistant is called Limo in one paragraph and Lemo in the next, or that the $12 tier advertises a lower limit than the $8 tier.

In practice the meaning-level defects are the ones that cost real money and the ones the team is most surprised by, because their existing tooling has been silently passing them for months. Budget your time accordingly: the probes are the first hour, the reading pass is where the audit earns its keep.

Before you start

Scope. Ask what matters if it is not obvious: which flows, which locales, desktop or mobile or both, and whether there is a known problem area. If the user just hands you a URL, audit the primary flow end to end and say what you covered.

Credentials. Never type a password into a field, even when the user offers one and asks you to. Open the sign-in page, fill any non-secret field, and ask them to type the secret themselves and confirm. Then continue on the authenticated session. Say this up front so it does not read as a refusal mid-task.

Viewport. Set an explicit size rather than trusting the pane default, and audit at the size that matches the product. A persistent bottom tab bar means mobile-first; auditing that at 1440px wide reports the wrong problems. Check both when the layout claims to be responsive.

Baseline the console before you touch anything. Console and network logs accumulate across a tab's lifetime, so errors from your earlier navigation will look like errors on the current page. Open a fresh tab per major route when the log matters.

Pass order

The order is deliberate: cheap and broad first, so the expensive reading pass is aimed at pages you already know are interesting.

1. Route sweep — probe-routes.js on the main navigation surface. Gives you the app's map, plus dead links and mislabelled destinations for free.
2. Structural probe — probe-core.js on every significant page.
3. Heuristics and perception probes — probe-heuristics.js and probe-perception.js on the primary task screens. Run it at the viewport the product is actually used at: Fitts distances and first-screen counts are viewport-dependent, so a mobile-first product measured at desktop width gives numbers that describe nobody.
4. Localisation probes — pick by what the page contains, and run both on a bilingual product:
   • probe-rtl.js on any page containing Arabic or rendering RTL
   • probe-ltr.js on any page in English or another LTR language A monolingual English product still needs probe-ltr.js: 1 items, a button with no room for a longer word and an ambiguous 03/04/2026 are defects today, and they are the expensive kind to discover on the day a second locale is added.
5. Parity pass — for a bilingual product, run probe-parity.js on the same route in each locale and compare the fingerprints. This finds the defect class neither single-locale pass can see, because it does not exist in either version alone: a feature renamed on one side, a card that renders in one language and not the other, a price that is stale in one locale.
6. Focus probe — press Tab, then probe-focus.js. Repeat across control types; focus styles are usually per-component.
7. Screenshot pass — capture each key viewport. Gestalt grouping, scan path, whether emphasis matches task priority, and first aesthetic impression cannot be derived from the DOM; assess them here, and say that you did.
8. Reading pass — the protocol below.
9. Data-layer check — for anything the reading pass flagged as contradictory or missing, find its source. See below.
10. Reproduction — re-test anything that looked intermittent.

Running the probes

Read the script file, then evaluate its contents in the page through whatever JavaScript-execution tool the browser integration provides. Each returns a JSON string.

• scripts/probe-core.js — contrast, tap targets, accessible names, duplicate destinations, head/SEO, heading outline, forms, layout overflow, performance
• scripts/probe-heuristics.js — Hick's Law and cognitive load, Fitts's Law and reachability, design-system conformance, interaction-state coverage, microcopy and error tolerance, the structural half of visual hierarchy
• scripts/probe-perception.js — Gestalt proximity and similarity, grid alignment, Miller chunking, Doherty response timing, emphasis inflation, clickability affordance, input constraints, top-of-screen real estate
• scripts/probe-rtl.js — the Arabic/RTL engine
• scripts/probe-ltr.js — the LTR/English engine: English plural templates, Title-vs-sentence case drift, ambiguous dates and ungrouped numbers, text expansion headroom, concatenated sentences, foreign-language runs missing lang, truncation, helper-text punctuation
• scripts/probe-parity.js — cross-locale fingerprint. Run it on the same route in each locale and compare the two outputs; it carries its own compareChecklist
• scripts/probe-focus.js — focus indicator; requires a real Tab keypress first, because programmatic .focus() does not trigger :focus-visible and you will report a false failure
• scripts/probe-routes.js — destination sweep; issues real GETs and skips anything that looks state-changing

Probe output is a lead list, not a report. probe-rtl.js in particular returns candidates — its dialect and spelling checks are heuristics over word lists. Read the samples before you write a finding.

The reading pass

This is the part that cannot be automated, so give it real attention rather than skimming. Extract the full visible text of each page, then read it the way a sceptical new user would.

Hunt for placeholder copy. Lorem ipsum is easy; the dangerous kind looks plausible. "A traditional description for the premium plan." "Feature test." "Test user." "Lorem". Names like foo, usa in lowercase among properly cased entries, a country list with six countries where two are in the wrong language. Anything that reads like it was typed to make the layout render.

Cross-check claims against the product. Marketing copy is often lifted from a template for a different business. If a plan promises certificates, live instructor sessions or downloadable courses, confirm those features exist. When they do not, this is not a copy nit — a paid page promising things the product cannot deliver is a commercial and legal exposure, and it should be the first finding in the report.

Look for internal contradictions, then go find the source of each — the data-layer section below explains why that single extra step decides whether a finding gets fixed or debated. Two numbers for the same thing on one card. A premium tier with a lower limit than the cheaper tier. A label that says one thing and a destination that does another. These survive because each half was written by a different person on a different day.

Check naming consistency across the whole product. One feature, one name. Assistant names, tier names, and the words for core objects ("quiz" vs "test", "folder" vs "collection") drift between screens and between locales. probe-parity.js reports nearDuplicateNames for one-character variants such as Limo/Lemo, but it only sees capitalised Latin words on the page it ran on — terminology that drifts between two different words ("Tests" here, "Quizzes" there) still needs you to read both locales side by side.

Test every empty state. An empty state without an action is a dead end, and new users hit these before they hit anything else. Ask of each: what does the user do next, and can they do it from here?

Trace the product's central promise. If onboarding says "upload your books", find the upload control. Count the taps. When the headline promise has no entry point on the main screen, that is usually the highest-impact finding in the whole audit and no automated tool will ever surface it.

Go to the data layer

When the reading pass turns up a contradiction, a suspicious number, or a section that looks empty, do not stop at the rendered text. Find where that value comes from — the API response the page fetched, the RSC or __NEXT_DATA__ payload, the config the component read. The network panel, or a fetch of the same endpoint from the page, usually gets you there in one step.

Two reasons this is worth the extra minute.

A number from the source cannot be argued with. "The premium tier shows 10 where the cheaper one shows 20" invites a discussion about whether you misread the layout. premium → dailyQuizzes: 10 next to plus → dailyQuizzes: 20, read from the response the page itself requested, ends the discussion.

It tells you which team owns the bug, which is the difference between a finding that gets fixed and one that gets passed around:

• Rendered value matches the data → the data is wrong. Content or backend.
• Rendered value differs from the data → the rendering is wrong. Frontend.
• The data holds something the UI never shows → a missing feature, and usually the cheapest fix in the whole report, because the hard part is already done. A localised price sitting unused in the response while the page displays only USD is worth more to the team than most defects you will find.

Report the source value alongside the rendered one. That pairing is the finding.

Stay read-only. Follow GET endpoints the page already called; never issue a write, and never replay a request that mutates state to see what it returns.

Intermittent defects

Some of the worst bugs do not reproduce on demand — a race between an auth guard and hydration, a CDN that intermittently serves a JS chunk as text/plain. The temptation is to report them as certain or to drop them. Do neither.

Test at least four times and report every attempt, including the ones that passed:

load 1 → 3533ms  /ar → /ar/login   ✗
load 2 → 7660ms  /ar → /ar/login   ✗
load 3 → no redirect within 12s    ✓
load 4 → no redirect within 12s    ✓

The variance is the finding — it tells the team this is a race condition, not a fixed timer, which points straight at the cause. A team that catches you overstating one finding will discount all of them, so this honesty is load-bearing.

Watch especially for failures with no user-visible error. A page that renders completely but whose JavaScript never loaded looks fine and responds to nothing. Users conclude the product is broken. Missing error boundaries are usually a bigger finding than the underlying flake.

Severity

Rank by consequence, not by how easy the defect is to describe.

• Critical — blocks a user, loses money, or misrepresents the product. Placeholder text on a pricing page, a broken primary flow, a purchase CTA weaker than an inert button, promises the product cannot keep.
• Major — the user completes the task but distrusts the product or takes a wrong turn. Broken plurals, mixed registers, contradictory numbers, dead-end empty states, buried core actions.
• Accessibility — cite the specific success criterion (1.4.11, 2.5.8, 4.1.2) with the measured number. Vague a11y findings get deprioritised; numbered ones get fixed.
• Note — real but low-consequence.

Then order the fix list by impact divided by effort. A one-line routing fix that repairs the main navigation outranks a design system overhaul.

Report format

Use this structure. See references/report-template.md for a worked example.

# <Product> — UX/UI Audit
Scope · account · viewports · date · pages covered

## Summary
Counts by severity. What works, stated as plainly as what does not.

## Findings
For each, in severity order:
  NN · [severity] · <page or route>
  A one-line claim written as a statement, not a question
  One or two sentences of consequence — who is hurt and how
  EVIDENCE: the measurement or the verbatim quote, in a code block
  FIX: the concrete change

## What works
Specific and measured, same as the findings. This is not padding — it tells
the team which foundations to build on and which not to touch.

## Where to start
Ranked by impact ÷ effort, with finding numbers.

Two habits that make reports land:

Credit what works, with numbers. "Contrast is 7.08:1 to 17.96:1 across both themes, above AAA" is as useful as any defect: it stops a team from re-litigating something already solved.

Write findings as claims, not questions. "The purchase CTA is a ghost button while the inert one is filled" beats "have you considered the button hierarchy?". You did the work; state what you found.

What the findings rest on

Say what a finding is grounded in, and be precise about which kind it is. Readers weigh a cited standard differently from a heuristic argument, and blurring the two costs you the benefit of both.

• Accessibility findings cite a success criterion (WCAG 2.2) with the measured value and the threshold. These are checkable against the source.
• Usability findings argue their case. They rest on established heuristics — Nielsen's ten are the usual frame — which have no pass/fail number, so the consequence has to be reasoned rather than asserted.
• Internationalisation findings cite the relevant spec where one exists: CLDR plural rules, UAX #9 for bidi, ECMA-402 for the fix.
• Some conventions here are this skill's own, not standards: the severity model, the impact ÷ effort ordering, the four-attempt reproducibility protocol, and the Arabic register and spelling word lists. Present those as judgment, never as authority.

references/foundations.md lists all of this in full, including what is deliberately out of scope. Read it before writing the method section of a report, and cite it when a reader asks where a finding comes from.

references/evaluation-matrix.md maps each design-psychology criterion — Hick, Fitts, Gestalt, Norman's three levels, visual hierarchy, microcopy — to the layer that can actually measure it: DOM, screenshot, or human judgement. Consult it when deciding how to evidence a usability claim, and respect the layer assignment. Measuring a criterion the wrong way produces a number that looks rigorous and is not: a contrast ratio estimated from a screenshot is a guess wearing a decimal point, and no screenshot can show that a stylesheet defines no :disabled state at all.

Never reduce the matrix to a single score. A composite hides which axis failed and invites optimising the metric instead of the product. Report per axis, and let the fix ordering carry the priority.

If the project has its own standards, they win. A house design system, content style guide or Arabic terminology guide takes precedence over everything above — look for one before starting, and say in the report which standard each finding was judged against.

Reference material

• references/foundations.md — the standards, heuristics and house conventions behind the findings, and the scope limits. Read when writing a report's method section or when a finding's basis is questioned.
• references/arabic-rtl.md — the linguistic and typographic rules behind the RTL probe: plural forms, numeral conventions, register, bidi, type. Read it when auditing an Arabic product or when interpreting probe-rtl.js output.
• references/wcag-thresholds.md — the criteria this skill checks, with the exact numbers and what each probe field maps to.
• references/report-template.md — a full worked report to model output on.