mblode/ui-audit

UI Audit

Audits the built frontend at the feature level (checkout, onboarding, a dashboard) for a dev with a PR open: "which of these hurt users in production, and which are nice-to-haves?" Reasons about code behavior (React/Next source) and rendered quality (accessibility, layout, performance, type, motion).

• IS: a diff-aware reviewer that detects which feature each changed file implements, runs that feature's playbook across behavior, rendered-quality, and Laws of UX rules, and emits a 3-tier ship verdict with file:line evidence and fixes.
• IS NOT: the product decision of what should exist (right interaction, action naming, reachable states → product-design), an agentic-app review (tool parity, trust cues, approval gates → ax-audit), a deep typography or motion pass (→ typography-audit or ui-animation), or a re-implementation of Lighthouse/axe/Chromatic (→ see "Defer to other tools").

product-design or ui-audit?

The dispatch signal is the artifact, not the topic. Both care about states and interaction, but act at different moments.

| You have... | The question is | Use | |---|---|---| | A brief, spec, mockup, intent, or a UI you decide about | What should exist: the right interaction, the action's name, which states should be reachable | product-design | | Code, a diff, or a running UI you decide on | Is the built result right: states covered, accessible, renders and behaves correctly, ready to ship | ui-audit |

Often both in sequence: product-design decides the states that must exist, ui-audit verifies the built code implements them.

Contents

• Audit workflow
• Rule layers and dispatch
• Scope: diff-aware by default
• Ship-readiness verdict
• Output adapters
• Suppressions
• Defer to other tools
• Reference files
• Related skills
• Gotchas
• Audit self-check

Audit workflow

Copy and track this checklist:

UI Audit progress:
- [ ] Step 1: Determine scope (PR diff via `git diff --name-only main` OR explicit file/folder)
- [ ] Step 2: Detect features in scope (sign-in / checkout / form / modal / list / dashboard / ...)
- [ ] Step 3: For each feature, run its playbook from references/feature-playbooks.md in order
- [ ] Step 4: For each check, load the named rule file (rules-modern/, rules-surface/, or rules/) and run its detection
- [ ] Step 5: Assign each finding a ship tier per references/ship-readiness.md (surface can bump tiers)
- [ ] Step 6: Build the JSON document, then render with the chosen output adapter
- [ ] Step 7: Run the audit-self-check; report INCOMPLETE if it fails

Step notes:

1. Scope. Diff by default; never the whole codebase (see Scope).
2. Detect features. Match semantics + filenames + routes: <form> with email + password is sign-in; role="dialog" is a modal; /checkout is checkout. Table: references/feature-playbooks.md.
3. Run playbooks. Each feature has 5-7 ordered checks. Run every one even when you expect a pass; passes feed the self-check's rulesRun count.
4. Load rules. Only the rule files the playbook names, never a whole folder (see dispatch).
5. Tier. Every finding gets release-blocker | fix-this-sprint | backlog; surface context bumps the default tier (sign-in/checkout up; marketing/internal-admin down).
6. Render. JSON first, then the adapter: the JSON keeps findings comparable across runs.
7. Self-check. Terminal evidence step; criteria below.

Rule layers and dispatch

Four layers, each with its own loading condition. Load rule files individually, on demand:

| Layer | Location | Load when | Size | |---|---|---|---| | 1: Feature playbooks | references/feature-playbooks.md | Always, at Step 2, since it is the entry point that names which Layer 2/3/4 rules to run | 12 playbooks | | 2: Modern failure modes (behavior) | rules-modern/<category>-<slug>.md | A playbook check names the rule, or a changed file matches the rule's category (forms, states, async, focus, mobile, dark-i18n, microcopy) | 28 rules | | 3: Rendered quality (surface) | rules-surface/<prefix>-<slug>.md | A playbook check names the rule, or a surface needs a rendered-quality check (a11y, interaction, forms, type, nav, layout, perf, motion, copy) | 33 rules | | 4: Laws of UX | rules/<prefix>-<slug>.md | A playbook explicitly names a Laws rule, or a finding needs cognitive/perceptual reasoning no Layer 2/3 rule covers | 21 rules (19 programmatic, 2 rubric) |

Layer-specific notes:

• Layer 2 (behavior) reasons from React/Next source: state coverage, form data loss, async races, focus management, optimistic-rollback, dark-mode/i18n. Index (categories, rule list, default tiers): rules-modern/_sections.md. Each rule file: detection greps, false-positive guards, surface-tier overrides, before/after fix.
• Layer 3 (rendered quality) reasons from rendered output: accessibility markup, keyboard operability, layout resilience, performance, motion, surface typography, copy specificity. Index + per-rule impact: rules-surface/_sections.md. A rule's frontmatter impact wins over its category default (e.g. perf-image-dimensions-and-priority is CRITICAL inside the HIGH perf- category).
• Layers 2 and 3 are complementary, not redundant: for a form, Layer 2 catches data loss on validation, Layer 3 catches a missing label or 14px mobile input. Run both when a feature has both in scope.
• Layer 4 is reserve. Expect 1-2 Laws findings per audit, not 21. Index: rules/_sections.md. The 2 rubric-kind rules score 1-5 against anchor tables in references/observational-rubrics.md: emit the score plus the verbatim anchor text. Pure design-decision scoring (choice architecture, information hierarchy, mental-model fit, dark-pattern framing, aesthetic polish) is out of lane: route it to product-design (and ui-design for visual direction), not a Laws finding here.
• When multiple layers fire on one issue, keep the most concrete framing. "Missing error state" (Layer 2) beats "high cognitive load" (Layer 4): concrete fix, specific surface match.

Scope: diff-aware by default

git diff --name-only main -- '*.tsx' '*.jsx' '*.ts' '*.js' '*.css' '*.module.css'

Audit only those files; surface the base in output: Auditing: 8 files changed vs main.

• Single component: git diff --name-only HEAD -- src/Component.tsx
• Full sweep: only on explicit request (--full src/), e.g. introducing the skill to a codebase. A default full sweep buries the 3 findings that matter under 60 that don't.

Ship-readiness verdict

Every audit opens with a verdict block before per-finding detail:

═══════════════════════════════════════════════════════════
SHIP VERDICT: ❌ NOT READY (1 release-blocker)

Surface count:           3 (CheckoutForm, PaymentStep, ConfirmStep)
Findings:                7
  Release blockers:      1   ⛔  Form data loss on validation (PaymentStep.tsx:42)
  Fix this sprint:       3   ⚠️
  Backlog:               3   📋

Defer-to (not audited here):
  Measured CWV (lab):    Run Lighthouse
  Bundle size:           Run size-limit
  Full WCAG conformance: Run axe-core
═══════════════════════════════════════════════════════════

Verdict computation: ✅ READY (0 blockers, ≤3 sprint) · ⚠️ READY WITH FOLLOW-UP (0 blockers, ≥4 sprint) · ❌ NOT READY (≥1 blocker) · 🚫 INCOMPLETE (self-check failed). Tier definitions, surface bump rules, and worked examples: references/ship-readiness.md.

Output adapters

All three formats render from the same JSON document. Templates and field mappings: references/output-adapters.md; strict schema: references/output-schema.md.

| Adapter | When | Format | |---|---|---| | Terminal table | Local dev, agent chat | Tight table grouped by surface, tier-sorted | | PR comment | GitHub / Vercel review | Markdown summary + inline comments with suggestion blocks | | CI JSON | Pipelines, merge gates | Strict JSON; gate with jq -e '.summary.releaseBlockers == 0' |

Suppressions

A finding is suppressed with an inline comment whose slug matches the rule:

{/* ui-audit-ignore:focus-not-restored, intentional: parent owns focus */}
<Dialog open={open} onClose={onClose}>

Suppressed findings still appear in the summary (summary.suppressed) so reviewers can verify intent.

Defer to other tools

ui-audit reasons statically; it does not measure runtime metrics or replace conformance scanners. It does surface-level a11y and performance checks (alt text, labels, contrast cues, image dimensions, font loading) but defers comprehensive measurement. When a finding belongs to another tool, link out, don't restate:

| Concern | Use instead | |---|---| | Measured Core Web Vitals (LCP, CLS, INP) | Lighthouse + web-vitals | | Full WCAG conformance scan | axe-core / eslint-plugin-jsx-a11y | | Visual regression | Chromatic / Percy | | Bundle size budgets | size-limit / bundle-analyzer | | Generic correctness bugs | CodeRabbit / Vercel Agent / pr-reviewer |

Full coverage map plus the gaps only ui-audit catches: references/defer-to-other-tools.md.

Reference files

| File | Read when | |------|-----------| | references/feature-playbooks.md | Steps 2-3: feature detection table + per-feature ordered checks | | references/states-coverage.md | Validating loading/empty/error/disabled coverage; the state matrix and mandatory state pairings | | references/ship-readiness.md | Step 5: tier definitions, surface bump table, verdict logic | | references/output-adapters.md | Step 6: verbatim terminal / PR-comment / JSON templates | | references/output-schema.md | Step 6: strict JSON schema and validation rules | | references/observational-rubrics.md | Scoring either Layer 4 rubric-kind rule (1-5 anchors) | | references/defer-to-other-tools.md | Deciding whether a concern is another tool's job | | references/craft-checklist.md | Optional polish sweep for details no rule encodes (hover affordances, pointer corridors, preserved scroll and object position, chrome hierarchy, theme-switch behavior) when polish or pre-release sign-off is in scope | | references/typography-checklist.md | Optional typography sweep (punctuation, measure, leading, OpenType basics, link styling, table numerals) when typography is named | | rules-modern/_sections.md | Layer 2 category index (behavior failure modes) | | rules-modern/<category>-<slug>.md | Step 4: running a named Layer 2 behavior check | | rules-surface/_sections.md | Layer 3 category index (rendered-quality, 9 prefixes) | | rules-surface/<prefix>-<slug>.md | Step 4: running a named Layer 3 rendered-quality check | | rules/_sections.md | Layer 4 category index (Laws of UX, 5 prefixes) | | rules/<prefix>-<slug>.md | Step 4: running a named Layer 4 Laws check |

Related skills

• product-design: the product decision, not the build. Route there when the question is "is this the right interaction or set of states", on a brief, spec, mockup, or intent.
• ax-audit: agentic-feature PRs (agent dashboards, tool-use UIs, trust patterns). Run both on an agentic feature: ax-audit for the agent layer, ui-audit for the surfaces around it.
• pr-reviewer: correctness bugs and code quality in the same diff; ui-audit covers only user-facing quality and behavior.
• typography-audit: deep typography (pairing, OpenType systems, brand and display type); ui-audit's type- rules and typography sweep are the shallower check.
• ui-animation: motion implementation and review (springs, easing, gestures); ui-audit's motion- findings route here for the fix.

Gotchas

• Don't audit the whole codebase by default. Full sweeps need an explicit request; otherwise the noise floor hides release-blockers.
• Don't skip feature detection and run every rule on every file. 82 rules × N files is a wall of backlog nits; per-feature playbook checks produce signal. Load only the rules-modern/, rules-surface/, rules/ files the playbook names.
• Don't assign release-blocker liberally. Reserve it for data loss, broken critical paths, and dark patterns. If everything is a blocker, the verdict stops gating merges.
• Don't prescribe fixes without the matching React 19 API. "Add a loading state" is unactionable; "wrap in <Suspense fallback={<InvoiceListSkeleton />}>" gets applied.
• Don't render markdown before the JSON document is complete. Adapters project the JSON; skipping it loses defaultTier/assignedTier/tierReason and makes runs incomparable.
• Don't double-report one issue across layers. When Layers 2, 3, and 4 all touch one issue, keep only the most concrete framing; emitting all inflates the count and splits the fix. Layers 2 and 3 catching different issues on one feature (data loss vs missing label) is expected, not a duplicate.
• Don't report a rendered-quality rule at its category default when the frontmatter overrides it. perf-image-dimensions-and-priority is CRITICAL (CLS) even though perf- is a HIGH category.
• Don't quote lawsofux.com verbatim. It is CC BY-NC-SA; every Layer 4 rule paraphrases. Quoting contaminates the output's license.
• Don't fabricate detections. No grep/Read evidence → result: "unknown" with a reason, never a fail. The self-check flags audits with >30% unknowns.

Audit self-check

Self-flag the audit INCOMPLETE if any are true:

• Fewer rules ran than planned (rulesRun < rulesPlanned)
• Over 30% of executed rules returned unknown
• Any fail/warn finding lacks a file:line citation
• Any fail/warn finding lacks a fix (and, where mechanical, a fixSnippet)
• No Read or Grep tool calls between findings (audit was guessed, not run)
• Every finding landed in the same tier (suspect blanket assignment)