Ibrahim-3d/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:

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

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

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

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

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

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

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

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

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

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