mblode/ui-audit

UI Audit

Final-pass audit workflow for web interfaces. Focuses on concrete issues with concrete fixes.

Trigger Cues

Use this skill when:

• 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
• The request mentions visual hierarchy, dense product chrome, headers, tabs, sidebars, icons, or separator cleanup

Audit Workflow

Copy and track this checklist during the audit:

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, gesture, and review details.
4. After fixes, rerun the relevant rules before finalizing.
5. When hierarchy or chrome cleanup is in scope, use the navigation, layout, and extra-polish sections in craft-checklist.md before reporting.

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Accessibility and Semantics | CRITICAL | a11y- | | 2 | Keyboard and Interaction | CRITICAL | interaction- | | 3 | Forms and Validation | CRITICAL | forms- | | 4 | Typography and Readability | HIGH | type- | | 5 | Navigation and Feedback | HIGH | nav- | | 6 | Layout and Resilience | HIGH | layout- | | 7 | Performance and Visual Stability | HIGH | perf- | | 8 | Motion and Theme Behavior | HIGH | motion- | | 9 | Content and Microcopy | MEDIUM | copy- |

Quick Reference

Read only what is needed for the current audit scope:

• 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

Example rule files:

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

Each rule file contains:

• Why the rule matters
• Incorrect example
• Correct example

Review Output Contract

Report findings in this format:

## 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.

Gotchas

• Do not dump every rule file into context. Load only the category prefixes relevant to the current scope (rules/<prefix>-*.md).
• Do not invent rule IDs in findings. Cite only ids that exist under rules/; if no rule fits, describe the issue without an id.
• Do not audit beyond the scope the user requested. Default is changed surfaces only; a full sweep must be explicit.
• Do not skip CRITICAL categories (a11y, interaction, forms) to reach visual polish faster. The priority order in the rule-category table is load-bearing.
• Do not report passes without checking. ✓ pass means the file was actually read against the loaded rules, not assumed clean.
• The anti-patterns in craft-checklist.md apply to UI code being audited, not to this skill's execution — do not mix the two when reporting findings.