UI Audit

UI Audit

Two audit modes for web apps. Pick the right one for the task.

Mode 1: UX / Product Review (no wireframe needed)

Evaluate the app as a real user would. No design spec required.

Workflow

1. Capture every screen at desktop (1280x800) and mobile (390x844):

python3 scripts/capture_screens.py <app_url> -o /tmp/ui-audit --config screens.json

Or manually navigate and screenshot each route.

2. For each screen, evaluate against the UX checklist (references/ux-review-checklist.md):

   • First impressions (what grabs attention, what confuses)
   • Information hierarchy (is the most important content most prominent?)
   • Navigation clarity (can the user find what they need?)
   • Interaction affordances (do clickable things look clickable?)
   • Content quality (clear labels, no jargon, helpful empty states)
   • Error and edge states (what happens when things go wrong?)
   • Mobile experience (not just a squeezed desktop, actually usable)
   • Loading and performance perception (skeleton states, progress indicators)
   • Accessibility basics (contrast, touch targets, focus indicators)

3. Cross-screen analysis:

   • Consistency (same patterns used everywhere?)
   • User flow (can a new user complete the core task without confusion?)
   • Visual cohesion (colors, spacing, typography consistent?)
   • Missing states (what screens/states are absent that users will hit?)

4. Output report grouped by severity (S1-S4), with screenshots and fix recommendations.

When to use Mode 1

• No wireframe or design spec exists
• Evaluating a competitor's product
• Post-launch UX review
• Checking if the app "feels right" independent of any spec
• Product feedback before a redesign

Mode 2: Wireframe Comparison (requires design spec)

Compare a live implementation against a static wireframe HTML file. Produces exact CSS property mismatches.

Prerequisites

• playwright Python package with Chromium
• Wireframe HTML file path
• Live app URL (deployed or localhost)

Workflow

1. Screenshot every screen at desktop and mobile:

python3 scripts/capture_screens.py <app_url> -o /tmp/ui-audit --config screens.json

2. Extract computed CSS from wireframe:

python3 scripts/extract_wireframe_specs.py <wireframe.html> --selectors selectors.json -o /tmp/wireframe-specs.json

3. Screen-by-screen comparison using references/audit-checklist.md:

   • Read wireframe HTML for that screen section
   • Read captured screenshot of the live app
   • Read implementation source (React/TSX/Vue/etc.)
   • Walk the per-component checklist (layout, spacing, colors, typography, borders, interactive states, icons, responsive)
   • For each mismatch: record severity, wireframe value, implementation value, file:line, fix

4. Output report grouped by screen, then severity.

When to use Mode 2

• A wireframe or design system HTML exists
• Pixel-accuracy matters (design handoff)
• Post-implementation design QA before launch
• Verifying that a redesign matches the approved mockup

Report Format

Both modes use the same severity scale and output format:

# UI Audit Report - [App Name]
**Date:** YYYY-MM-DD
**Mode:** UX Review / Wireframe Comparison
**URL:** [url]
**Screens Audited:** [list]

## Summary
- Total issues: X
- S1 (Critical): X
- S2 (Major): X
- S3 (Minor): X
- S4 (Cosmetic): X

## Findings

### [Screen Name] - [Viewport]

#### [Issue Title]
- **Severity:** S2
- **Category:** Visual Hierarchy / Interaction / Content / Layout / Responsive
- **What:** [Description of the problem]
- **Why it matters:** [Impact on user experience]
- **Fix:** [Specific recommendation]
- **File:** [file:line if applicable]

[screenshot if available]

Severity Levels

Resources

• references/ux-review-checklist.md - Standalone UX/product review checklist
• references/audit-checklist.md - Per-component wireframe comparison checklist
• references/wireframe-screens.md - Template for screen inventory and selector mappings
• scripts/capture_screens.py - Playwright screenshot automation (config-driven)
• scripts/extract_wireframe_specs.py - Computed CSS extraction from wireframe HTML