/eval-ui-ux

name: eval-ui-ux
description: "Specialized UI/UX evaluator for the Evaluate-Loop. Use this for evaluating UI shell tracks, design system tracks, screen implementation tracks, or any track where the primary deliverable is visual/interactive UI. Checks design system adherence, visual consistency, layout structure, responsive behavior, component states, animations, accessibility baseline, and usability check (copy quality). Dispatched by loop-execution-evaluator when track type is 'ui', 'design-system', or 'screens'. Triggered by: 'evaluate UI', 'UI review', 'design review', 'visual audit'."

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 =