| name | review-ui |
| description | Review any UI for quality issues -- visual defects, alignment, spacing, typography, color, responsiveness, motion, accessibility, performance, and anti-patterns. Works across web, iOS, Android, desktop, and screenshots. Standard mode dispatches 2-3 specialists based on scope and platform. For the full 5-specialist + verifier team pass, use review-ui-full.
Triggers: "review this UI", "check the UI quality", "review my screen", "is this good quality", "check alignment", "review the design", "audit this interface", "does this look right", "check my layout", "review for quality issues", "find UI problems", "review-ui". |
| argument-hint | [path | file | directory | screenshot | "diff" | "staged" | "pr" | "all"] |
| allowed-tools | Bash, Read, Grep, Glob, TodoWrite, Agent |
Review UI
Coordinate a UI quality review: determine scope, gather context, dispatch 2-3 specialists, and present a merged report.
Step 1: Determine scope
Resolve the argument to a concrete file or evidence list:
| Argument | Meaning |
|---|
(empty) or diff | Uncommitted + staged changes, filtered to UI-relevant files |
staged | Only staged files |
pr | Diff vs main/master |
<file> | Single file |
<directory> | All UI files in dir |
<screenshot> | Screenshot file(s) for screenshot-only review |
all | Entire project (excluding node_modules, dist, build, .build, Pods, DerivedData) |
UI-relevant file extensions
Web: *.tsx, *.jsx, *.vue, *.svelte, *.css, *.scss, *.html
iOS: *.swift (containing SwiftUI views), *.storyboard, *.xib
Android: *.kt (containing Compose), *.xml (layouts)
Screenshots: *.png, *.jpg, *.jpeg, *.webp
If empty scope, tell user and suggest alternatives. If >50 files, warn and ask.
Step 2: Detect platform
| Signal | Platform |
|---|
package.json with react/vue/svelte/next | Web |
*.swift with import SwiftUI | iOS/Apple |
build.gradle or *.kt with @Composable | Android |
*.html / *.css only | Web (static) |
| Screenshot files only | Screenshot-only mode |
Step 3: Gather context (parallel)
Web:
package.json -- framework, Tailwind, design librariesglobals.css / tailwind.config.* -- token systemtsconfig.json -- strictness
iOS:
- Asset catalog -- named colors, images
- Project structure -- SwiftUI vs UIKit mix
- Info.plist -- supported orientations, scenes
Android:
build.gradle -- min SDK, Material versionthemes.xml / colors.xml -- design system- Compose vs XML split
Step 4: Decide which specialists to dispatch
Code or browser review
| Condition | Specialists |
|---|
| Any review | ui-review:ui-visual-reviewer (always) |
| Any review | + ui-review:ui-accessibility-reviewer (always) |
| Web platform detected | + ui-review:ui-responsive-reviewer (default for web) |
| iOS/Android adaptive layout | + ui-review:ui-responsive-reviewer |
| Motion/animation in scope | + ui-review:ui-motion-reviewer |
| Performance concern | + ui-review:ui-runtime-reviewer |
Default for web: visual + accessibility + responsive (3 agents).
Default for mobile native: visual + accessibility (2 agents).
Screenshot-only review
When only screenshots are provided (no code, no running app):
| Specialists | Notes |
|---|
ui-review:ui-visual-reviewer | Full visual review on screenshots |
ui-review:ui-accessibility-reviewer | Limited: contrast, target size estimation, semantic guesses. Findings marked lower confidence. |
Do NOT dispatch: responsive (can't resize), motion (can't observe), runtime (can't measure).
Tell the user which dimensions could not be reviewed:
"Screenshot-only review covers visual quality and estimated accessibility. Responsive behavior, motion quality, and runtime performance require code access or a running application."
Step 5: Construct prompts
Each agent gets a self-contained prompt with:
- Absolute file paths or screenshot paths
- Platform identification
- Project context (framework, tokens, config)
- Instruction to read their plugin references BEFORE reviewing
- Evidence availability (Playwright available? Code access? Screenshots only?)
- Output in strict finding format from
01-universal-rubric.md
Step 6: Dispatch agents in parallel
Dispatch all chosen specialists in parallel using the Agent tool. Send multiple Agent calls in a single message. Omit model on each call -- specialists inherit the session model (always the strongest available Claude):
// Dispatch all in parallel -- one message, multiple tool calls
Agent({
subagent_type: "ui-review:ui-visual-reviewer",
prompt: "<scope, platform, context, evidence availability>",
description: "Visual quality review"
})
Agent({
subagent_type: "ui-review:ui-accessibility-reviewer",
prompt: "<scope, platform, context, evidence availability>",
description: "Accessibility review"
})
Agent({
subagent_type: "ui-review:ui-responsive-reviewer",
prompt: "<scope, platform, context, evidence availability>",
description: "Responsive review"
})
Execution mode
Specialists inherit the session model. If the session model is already the strongest available tier and scope is small (1-2 files, one dimension), the coordinator may run the review inline in the main context instead of dispatching -- never dispatch to, or wait on, a specific named model. Dispatching stays the default for multi-specialist parallel reviews; inline execution never grants write access -- findings stay advisory and files stay unmodified, exactly as the read-only specialist agents behave.
Step 7: Merge and present report
Standard mode has no dedicated verifier agent -- the coordinator applies the verifier's rules
during the merge:
- Collect findings from all agents
- Deduplicate and group using the "Deduplication rules" and "Grouping" sections of
${CLAUDE_PLUGIN_ROOT}/agents/ui-verifier.md (same element + same issue = keep the more
specific finding; cross-dimension contrast/clipping/reduced-motion overlaps merge into one)
- Validate severities against the "Severity validation" table in the same file (taste never
at HIGH/CRITICAL; accessibility blockers never below HIGH)
- Enforce the geometry evidence rule (
${CLAUDE_PLUGIN_ROOT}/references/09-evidence-pipeline.md,
"Geometry evidence rule"): any spatial claim without geometry evidence is capped at
"Possible issue -- geometry measurement needed"
- Re-rank by severity (CRITICAL first) and number sequentially
## UI Quality Review
**Scope:** <files, count>
**Platform:** <detected platform>
**Specialists:** <which were dispatched>
**Evidence level:** <code + browser / code-only / screenshot-only>
**Findings:** N CRITICAL, N HIGH, N MEDIUM, N LOW, N TASTE
**Verdict:** <one line>
[numbered findings list]
Before presenting (all must pass)
| Check | Pass condition |
|---|
| Finding format | Every finding carries [SEVERITY] [CONFIDENCE] plus Surface, Issue, Why it matters, Evidence, Recommended change |
| Evidence present | No finding with an empty or vague Evidence field ("looks off" fails) |
| Geometry rule | No spatial claim above "Possible issue" confidence without geometry evidence |
| Ordering | Findings numbered sequentially, CRITICAL first, TASTE last |
| Coverage disclosure | Dimensions NOT reviewed (undispatched specialists, screenshot-only limits) named in the report header |
Fix formatting failures during the merge; if a finding's substance is unverifiable, drop it
and record the drop under a "Merge notes" line in the report.
Step 8: Write learnings
If the review surfaced non-obvious patterns, write to GoodMem Learnings.
