UI Audit

Trigger Cues

• The user asks for a UI quality audit, design QA, polish pass, or pre-release review
• The task requires accessibility, keyboard, form usability, typography, or interaction checks
• The request includes loading/error/empty states, responsiveness, or visual stability checks

Audit Workflow

Audit progress:
- [ ] Step 1: Scope changed surfaces and select relevant categories
- [ ] Step 2: Run CRITICAL checks first (a11y, interaction, forms)
- [ ] Step 3: Run HIGH/MEDIUM checks for the same surfaces
- [ ] Step 4: Report findings with file:line and concrete fixes
- [ ] Step 5: Re-check touched files and mark passes

1. Audit only changed pages/components unless a full sweep is requested.
2. Prioritize

   CRITICAL

   and

   HIGH

   findings before medium-priority polish.
3. For motion behavior, also apply

   ui-animation

   for timing/easing/reduced-motion details.
4. After fixes, rerun the relevant rules before finalizing.

Rule Categories by Priority

a11y-

interaction-

forms-

type-

nav-

layout-

perf-

motion-

copy-

Quick Reference

• Category map and impact rationale:

  rules/_sections.md

• Rule-level guidance and examples:

  rules/<prefix>-*.md

• Full craft sweep:

  craft-checklist.md

• Typography deep sweep:

  typography-checklist.md

rules/a11y-semantic-html-first.md
rules/forms-inline-errors-first-focus.md
rules/perf-image-dimensions-and-priority.md

• Why the rule matters
• Incorrect example
• Correct example

Review Output Contract

## UI Audit Findings

### path/to/file.tsx
- [CRITICAL] `a11y-icon-controls-labeled`: Icon button is missing an accessible name.
  - Fix: Add `aria-label="Close dialog"` (or visible text label).

### path/to/clean-file.tsx
- ✓ pass

• Group findings by file.
• Use

  file:line

  when line numbers are available.
• State issue and propose a concrete fix.
• Include clean files as

  ✓ pass

  .