Structured UI review sessions combining bug hunting, UX assessment, and visual verification. Use when reviewing implemented UIs for quality, usability, and correctness.
Systematic approach to reviewing user interfaces — finding bugs, assessing UX quality, and verifying visual correctness through screenshot-driven analysis.
Capture screenshots of every distinct UI state.
[!IMPORTANT] For this repo's web UI: CC agents call the MCP API for visual testing using the
visual-reviewskill (). CC agents must NOT run Playwright or capture screenshots directly. The commands below apply only to ux-visual-reviewer-resident agents or platform-specific contexts (iOS/watchOS).
.agent/skills/visual-review/SKILL.md# iOS/iPad simulator
xcrun simctl io DEVICE_UUID screenshot /tmp/ui-baseline.png
# watchOS simulator
xcrun simctl io DEVICE_UUID screenshot /tmp/watch-baseline.png
Document each state you can reach:
Use the UX Heuristic Checklist (below) to systematically evaluate each screen.
Create a prioritized report with embedded screenshots showing issues.
[!CAUTION] Every P-level finding must be fixed — not deferred, dismissed, or rationalized. Agents must NEVER classify findings as "acceptable," "cosmetic-only," or "not the major issue." UX Sandbox checks are explicitly refined by the project owner and are intentional. If the NRQA or visual review flags it, fix it. The only exception is a single finding estimated at >2 hours of work — document it as a follow-up issue with user confirmation.
Rate each item ✅ (good), ⚠️ (needs work), or ❌ (broken):
| Category | Examples | Priority |
|---|---|---|
| Crash | App crashes on action, unhandled exception | P0 |
| Data Loss | User input lost, unsaved changes discarded | P0 |
| Functional | Button does nothing, wrong data displayed | P1 |
| Visual | Layout broken, overlapping elements, wrong colors | P1 |
| UX | Confusing flow, missing feedback, poor affordance | P2 |
| Performance | Slow load, janky scroll, delayed response | P2 |
| Polish | Minor spacing, subtle animation issues | P3 |
| Accessibility | Missing labels, low contrast, no keyboard nav | P2 |
# UI Review: [Feature/Screen Name]
**Date:** YYYY-MM-DD
**Platform:** [Web/iOS/iPadOS/watchOS/Electron]
**Reviewer:** [Agent name]
## Summary
[1-2 sentence overall assessment]
## Screenshots

## Findings
### P1 — Must Fix
1. **[Title]** — [Description]
- Screenshot: [reference]
- Location: [file:line]
- Suggested fix: [approach]
### P2 — Should Fix
...
### P3 — Nice to Have
...
## UX Scorecard
| Category | Score |
|----------|-------|
| Visual Design | ✅ / ⚠️ / ❌ |
| Interaction | ✅ / ⚠️ / ❌ |
| Content & Data | ✅ / ⚠️ / ❌ |
| Performance | ✅ / ⚠️ / ❌ |
[!IMPORTANT] CC agents run visual reviews by calling the MCP API via the
visual-reviewskill (.agent/skills/visual-review/SKILL.md). CC agents must NOT run Playwright or testing tools directly.
Tier 1 — UX Visual Reviewer Playwright (layout, structure, styling):
file:// and http://127.0.0.1:3050/gui/ — tests HTML/CSS/DOMTier 2 — Live Browser Evidence (data, functional proof):
http://127.0.0.1:3050/gui/ serves the full GUI with browser-renderer.js for HTTP-based data loadingBoth tiers required. Tier 1 alone proves only structure. Tier 2 alone proves only one moment in time. Together they provide comprehensive evidence. CC agents verify the returned artifacts meet the gate checklist.