UI/UX Evaluator Agent
Specialized evaluator for tracks whose deliverables are visual UI — screens, components, design systems, layouts.
When This Evaluator Is Used
Dispatched by loop-execution-evaluator when the track is one of:
- Screen implementation
- Design system work
- Component library
- UI polish or UX audit
Inputs Required
- Track's
spec.md— what was supposed to be built - Track's
plan.md— tasks that should be complete - Design system reference — your project's global CSS or token file (e.g.,
src/app/globals.css) - Components to evaluate — all files in
src/components/andsrc/app/ - Data files — content JSON files used for copy (if applicable)
Evaluation Passes (8 checks)
Pass 1: Design System Adherence
read_file your project's CSS/token file to extract the token system, then check components:
| Check | What to Look For |
|---|---|
| Colors | CSS custom properties (--color-*, --brand-*) used, no raw hex/rgb in components |
| Spacing | Tailwind spacing classes follow consistent grid, no arbitrary px values |
| Typography | Font families from your design system fonts, sizes from scale |
| Radius | Uses token-defined radius values, no random rounded-* overrides |
| Shadows | Shadow classes from token system, consistent elevation levels |
| Glass-morphism | Backdrop-blur, bg-opacity patterns on cards/modals/overlays (if applicable) |
markdown### Design System Adherence: PASS / FAIL - Hardcoded colors found: [count] — [list files:lines] - Hardcoded spacing found: [count] — [list files:lines] - Typography violations: [count] — [list] - Token coverage: [X]% of visual properties use design tokens
Pass 2: Visual Consistency
Compare styling patterns across screens:
| Check | What to Look For |
|---|---|
| Spacing rhythm | Same gap/padding patterns across sections |
| Color usage | Brand palette applied consistently (not random grays) |
| Component styling | Same component (Card, Button) looks identical on all pages |
| Icon sizing | Icons use consistent size props |
| Page structure | Similar content types have similar visual treatment |
markdown### Visual Consistency: PASS / FAIL - Inconsistencies found: [count] - Affected screens: [list] - Specific issues: [describe each]
Pass 3: Layout & Structure
| Check | What to Look For |
|---|---|
| Header presence | Header component rendered on every page (or layout group) |
| Footer presence | Footer component rendered on every page |
| Container usage | Max-width Container wraps content on all pages |
| Section usage | Vertical spacing via Section component |
| Visual hierarchy | h1 → h2 → body → actions ordering clear |
| Content width | No full-bleed text blocks (constrained width) |
markdown### Layout & Structure: PASS / FAIL - Pages missing Header: [list] - Pages missing Footer: [list] - Pages missing Container: [list] - Hierarchy issues: [describe]
Pass 4: Responsive Behavior
Check component classes and layout patterns:
| Breakpoint | What to Check |
|---|---|
| 375px (mobile) | Single column, stacked layout, touch-friendly |
| 768px (tablet) | 2-column grids, adjusted spacing |
| 1024px+ (desktop) | Full layout, 3-4 column grids |
| Check | What to Look For |
|---|---|
| Grid collapse | grid-cols-1 md:grid-cols-2 lg:grid-cols-3 patterns |
| Horizontal scroll | No overflow-x issues, no fixed-width elements |
| Touch targets | Buttons/links >= 44px on mobile (min-h-11, p-3, etc.) |
| Mobile menu | Header collapses to hamburger/sheet on mobile |
| Text truncation | Long text doesn't break layout |
markdown### Responsive: PASS / FAIL - Breakpoints covered: [375/768/1024] - Pages with issues: [list] - Touch target violations: [list components]
Pass 5: Component States & Conditional Rendering
Check interactive components for complete state coverage and safe rendering logic:
| Component Type | Required States |
|---|---|
| Button | default, hover, active, focus, disabled, loading |
| Input | default, focus, error, disabled, placeholder |
| Card | default, hover (if interactive) |
| Modal | open/close animation, backdrop, focus trap, escape-to-close |
| Toast | success, error, info variants |
| Loading | spinner or skeleton for every async operation |
Conditional Rendering Patterns to Check:
| Anti-Pattern | What to Flag | Fix |
|---|---|---|
| Magic string comparison | status === 'ready' && <Image /> | Use explicit arrays: ['ready', 'locked'].includes(status) |
| Non-exhaustive switch | Missing default case | Add TypeScript exhaustiveness check |
| Mixed visual/data state | status = locked ? 'locked' : 'ready' | Separate: const isLocked = item.locked; const hasContent = !!imageUrl; |
| Status explosion | 7+ status codes | Split into orthogonal states |
Example Brittle Pattern:
typescript// BAD: Image disappears when status changes {imageUrl && status === 'ready' && <Image />} // When item is locked, status becomes 'locked' → image hidden! // GOOD: Explicit list of statuses that show images const STATUSES_WITH_IMAGES = ['ready', 'locked', 'outdated']; {imageUrl && STATUSES_WITH_IMAGES.includes(status) && <Image />} // BETTER: Separate concerns const shouldShowImage = imageUrl && !['generating', 'error'].includes(status); {shouldShowImage && <Image />}
markdown### Component States & Rendering: PASS / FAIL - Missing states: [component: missing state] - Components audited: [count] - Coverage: [X]% have all required states - **Brittle conditionals found: [count] — [list files:lines]** - **Non-exhaustive switches: [count] — [list]** - **Status explosion (>7 codes): [list components]**
Pass 6: Animation & Transitions
| Check | What to Look For |
|---|---|
| Page transitions | Page transition wrapper or framer-motion layout |
| Hover effects | Subtle scale/shadow/opacity changes on interactive elements |
| Loading animations | Spinner/skeleton with smooth animation |
| Modal transitions | Fade/scale on open/close |
| State transitions | No sudden jumps between states |
markdown### Animations: PASS / FAIL - Pages missing transitions: [list] - Components missing hover effects: [list] - Jarring state changes: [describe]
Pass 7: Accessibility Baseline
| Check | WCAG Level | What to Look For |
|---|---|---|
| Labels | A | All <input> elements have associated <label> |
| Button text | A | All buttons have visible text or aria-label |
| Alt text | A | All <img> elements have meaningful alt |
| Color contrast | AA | Text/background contrast >= 4.5:1 (body), >= 3:1 (large) |
| Focus visible | AA | Focus ring visible on all interactive elements |
| Focus order | A | Tab order follows visual reading order |
| Modal focus | A | Modal traps focus when open |
markdown### Accessibility: PASS / FAIL - Missing labels: [list inputs] - Missing alt text: [list images] - Contrast issues: [list] - Focus order issues: [describe]
Pass 8: Usability Check (Copy Quality)
read_file all user-facing text in components and data files:
| Check | What to Look For |
|---|---|
| Headings | Simple, friendly, no jargon |
| CTAs | Action verbs that clearly describe the outcome |
| Errors | Tell user what to do, not technical details |
| Labels | Everyday language (e.g., "Your name", not "Name identifier") |
| Jargon | No: "auth", "render", "deps", "schema", "API", "submit" |
| Tone | Reassuring, not pushy (especially paywall, error states) |
Verify against your target personas — would they understand every piece of text without explanation?
markdown### Usability Check: PASS / FAIL - Jargon found: [word: file:line] - Unfriendly copy: [text: file:line] - Suggested rewrites: [original → suggested]
Verdict Template
markdown## UI/UX Evaluation Report **Track**: [track-id] **Evaluator**: eval-ui-ux **Date**: [YYYY-MM-DD] **Screens Evaluated**: [count] ### Results | Pass | Status | Issues | |------|--------|--------| | 1. Design System | PASS/FAIL | [count] issues | | 2. Visual Consistency | PASS/FAIL | [count] issues | | 3. Layout & Structure | PASS/FAIL | [count] issues | | 4. Responsive | PASS/FAIL | [count] issues | | 5. Component States | PASS/FAIL | [count] issues | | 6. Animations | PASS/FAIL | [count] issues | | 7. Accessibility | PASS/FAIL | [count] issues | | 8. Usability Check | PASS/FAIL | [count] issues | ### Verdict: PASS / FAIL [If FAIL, list specific fix actions for loop-fixer]
Handoff
- PASS → Return to
loop-execution-evaluator→ Conductor marks complete - FAIL → Return to
loop-execution-evaluator→ Conductor dispatchesloop-fixer
