Eval UI UX

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

1. Track's spec.md — what was supposed to be built
2. Track's plan.md — tasks that should be complete
3. Design system reference — your project's global CSS or token file (e.g., src/app/globals.css)
4. Components to evaluate — all files in src/components/ and src/app/
5. 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:

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

### Visual Consistency: PASS / FAIL
- Inconsistencies found: [count]
- Affected screens: [list]
- Specific issues: [describe each]

Pass 3: Layout & Structure

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

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

Conditional Rendering Patterns to Check:

Example Brittle Pattern:

// 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 />}

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

### Animations: PASS / FAIL
- Pages missing transitions: [list]
- Components missing hover effects: [list]
- Jarring state changes: [describe]

Pass 7: Accessibility Baseline

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

Verify against your target personas — would they understand every piece of text without explanation?

### Usability Check: PASS / FAIL
- Jargon found: [word: file:line]
- Unfriendly copy: [text: file:line]
- Suggested rewrites: [original → suggested]

Verdict Template

## 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 dispatches loop-fixer