jwp23/joe-bag-of-tricks/ux-audit

UX Audit

Overview

Core principle: Report the UI's problems before your human partner has to. A batch of frontend work is not done when it functions — it is done when someone has looked at it at every viewport it will be used at, and written down what is wrong.

Roughly half of user-reported UI complaints are mechanically detectable: text clipped by a column, a panel that ate the table, an abbreviation nobody outside the codebase can read. This skill runs that pass first.

When to Use

• A UI feature batch is complete and about to be handed over
• Before asking for design feedback — clear the mechanical findings first
• Not for: a backend change with no rendered surface, or a UI you have already audited unchanged

Mechanical vs. Judgment

Two different things happen in one run. Do not confuse them.

A script cannot decide whether a label is comprehensible or a layout has a focal point. For 3 and 5 the script's only job is to capture evidence — a labels file and a screenshot. The finding is yours. Never report a judgment check as "PASS" because the script exited 0.

Running It

REQUIRED BACKGROUND: scripted-browser-verification. The audit's browser work obeys its rule without exception — one Node Playwright script, all assertions in code, run via Bash, headless. Never step through interactive browser tool calls.

You extend the project's existing `verify.js`; you do not write an audit script. Copy ux-checks.js in beside it once, then add check entries:

const { sweepTruncation, assertPrimaryContentShare, captureLabels } = require('./ux-checks.js');
const tag = (page) => `${page.viewportSize().width}x${page.viewportSize().height}`;
const checks = [
  {
    name: 'ux audit — no truncated text on the dashboard',
    path: '/',
    async run(page) {
      await sweepTruncation(page, {
        reportFile: path.join(config.evidenceDir, `truncation--${tag(page)}.json`),
      });
    },
  },
  {
    name: 'ux audit — primary content keeps most of the viewport',
    path: '/',
    async run(page) {
      await assertPrimaryContentShare(page, {
        selector: config.primaryContent,
        minShare: config.primaryContentMinShare,
      });
    },
  },
  {
    name: 'ux audit — capture labels for comprehensibility review',
    path: '/',
    async run(page) {
      await captureLabels(page, {
        reportFile: path.join(config.evidenceDir, `labels--${tag(page)}.json`),
      });
    },
  },
];

Everything project-specific lives in verify.config.json — viewports, primaryContent, primaryContentMinShare, evidenceDir, and the routes each check visits. Never hardcode a viewport size, selector, ratio, or URL in a check. If the project has no viewport matrix yet, agree one with your human partner and write it to the config; a matrix normally spans full screen, laptop, and a half-width tile, because a half-width tile is where truncation shows up first.

For check 6, point checks at the app's zero-data, feature-absent, and longest-value fixtures. Same sweeps, different routes.

Then: run once, read the labels file and the screenshots, write the findings.

Output Contract

A findings list the standard fix loop can consume — one line per finding:

[SEVERITY] check — what is wrong — where — evidence path

Every finding cites evidence — a screenshot path, or an entry in the truncation/labels file. A finding with no evidence is an opinion; either get the evidence or drop it. Report "no findings" only after both the mechanical run passed and you looked at the screenshots.

Red Flags - STOP

• Reporting judgment checks as passed because the script exited 0
• Auditing at one viewport because "it looks fine on my screen"
• Hardcoding a viewport, selector, or ratio into a check instead of the config
• Writing a fresh audit script beside the project's verify.js
• A finding with no screenshot or evidence file behind it
• Handing the batch over before the audit, planning to audit "if they complain"

Common Rationalizations