/ux-review — five reviewers in one pass
Parallel AI review system for usability, accessibility, design-system consistency, mobile readiness, and behavioral risk, producing a scored report and fix loop.
Problem
“Review my UI” is a bag of overlapping questions. Is the contrast legal? Are the touch targets reachable? Does the copy carry its weight? Are there dark patterns? Is the mobile breakpoint a lie? Running each as a separate prompt gives you five disconnected reports, no shared severity scale, and no way to compare yesterday’s run to today’s.
I wanted one command that returned one number — defensibly. A composite score that I could chase, that wouldn’t lie when a WCAG failure was hiding behind a strong emotional-design pass, and that produced the same answer twice in a row on the same code.
Approach
/ux-review fans out five reviewer agents in parallel, each anchored to a checklist file:
| Agent | Covers | Reference |
|---|---|---|
| A | WCAG 2.1 AA contrast + ARIA | wcag-checklist.md |
| B | Design system, HIG, touch targets, Vercel polish | vercel-polish-guidelines.md |
| C | Nielsen heuristics + UX writing | nielsen-norman-heuristics.md |
| D | Mobile readiness (statically verifiable) | mobile-guidelines.md |
| E | Behavioral science + dark patterns + emotional design | three references |
Each agent emits findings with file:line. The orchestrator merges them, deduplicates cross-dimension overlaps (touch targets get flagged by A and B — one finding, both tags), normalizes every dimension to 0–100, and applies mode-aware weights to produce a composite.
Three modes, mutually exclusive:
- Default — all five agents.
--quick(also/audit) — compliance only. A + B.--no-compliance(also/critique) — UX quality only. C + D + E. Propose-only fixes.--only=<dims>— arbitrary subset. Weights renormalize. Dark-pattern detection runs regardless — it’s a Critical-floor input and can’t be opted out of.
The scoring layer that keeps the number honest
The composite is a weighted average. Without guardrails, a strong reflective-emotional score will dilute a single WCAG legal-exposure finding into a B+. Three mechanisms prevent that:
- Dark penalty.
min(25, 5 × dark_pattern_count)subtracted from the raw composite. A confirmed Brignull pattern can’t be perfumed. - Critical floor. Unresolved Critical WCAG findings cap the score at 77 (C+). Unmitigated dark patterns cap at 72 (C-). Both apply → take the lower cap. The cap is surfaced inline: “Composite: 88 → capped at 77 (C+) due to 2 unresolved Critical compliance findings.”
- Regression alert. Each run reads the most recent prior report for the same scope. Any dimension dropping ≥3 points (or a letter-grade drop on Composite) renders a Regression Alert before the Executive Summary, with likely-cause inference.
This is what makes /ux-review-loop’s ≥95% chase honest. You can’t compose-average your way to an A.
Auto-fix, then bisect on failure
Step 5 applies safe fixes: failing non-brand contrast colors, missing aria-label / aria-hidden / role, touch targets pushed to 48px, Font Awesome Pro → Free swaps. Every fix is recorded in an ordered applied_fixes list with file:line, finding ID, and a reversible diff.
Step 6 runs the build. If it passes, ship the report. If it fails, bisect over applied_fixes:
- Split suspects in half.
- Revert the later half. Rebuild.
- Build passes → culprit is in the reverted half. Recurse into it.
- Build fails → culprit is in the earlier half. Restore the later half, recurse into the earlier.
- Budget cap:
ceil(log2(n)) + 2builds. Exceeded → revert everything and list as manual.
A passing baseline build (step 0b) guarantees a known-good reference, so the bisect always terminates with the actual culprit isolated. The ~95% of fixes that are safe get preserved — far better than the previous LIFO-revert-then-give-up approach that threw out the whole batch on a single bad swap.
Ownership boundaries
/ux-review does not own everything it flags. The boundary is deliberate:
- Token drift — hardcoded colors, spacing, radius literals are reported but not auto-fixed. Replacement is owned by
/normalize. - Performance findings — route to
/optimize. - Edge cases, i18n, overflow — route to
/harden. - Token-system gaps — Agent B reports “no spacing tokens found” rather than flagging hundreds of drift findings against an empty set.
Step 9 of the skill renders a follow-up map at the bottom of every report — “these N findings belong to /normalize; run it next.” Composability without overstep.
Why one number matters
Because designers ship in environments where “looks better” is the loudest signal. A composite is something you can chase, regress against, and refuse to commit until it crosses a bar. /ux-review-loop runs /ux-review repeatedly, applies P0/P1 fixes, and re-runs until composite ≥ 95% or 5 passes. The arc that shows up on the homepage — D/66% → A/93% — is the loop, but the loop only works because the underlying score is honest.
The first review tells you what’s broken. The fourth review tells you whether you actually fixed it. Without a stable number, the fourth review is vibes.
What I’d do differently
- Runtime contrast is opt-in (
--runtime-contrast). It spins up the dev server and reads computed colors via Playwright MCP — solves the “nested var() / theme branch” cases that static resolution flags as unresolvable. It should probably be on by default for theme-aware projects; the 30s cost is worth it when the alternative is missing a real failure. - The cached project context fingerprint (
sha1(mtime(package.json) + mtime(styles_file))) is too coarse. Touchingpackage.jsonfor an unrelated dep bump invalidates detection. A content hash would be cheaper than re-detecting. - Agent E always runs dark-pattern detection, even in
--only=subsets that exclude it — that’s correct, but the “reduced mode” branch is a special case that’s bitten me twice during skill edits. Should be a separate Agent F with one job. - Findings JSON doesn’t carry the fix’s reversibility metadata the way
applied_fixesdoes. If a downstream tool wanted to drive the bisect from outside the skill, it’d have to re-derive the diff. Worth surfacing in--jsonoutput.