## Definition
A **UI Verifier Agent** is a specialized [[Headless Agent in CI]] that drives a real browser (via Playwright or a dedicated MCP server) to load affected routes, capture screenshots across standard viewports, and report visual regressions — overflow, clipped text, broken contrast, console errors — for every frontend change in a diff.
## Why Screenshots Over Unit Tests
A unit test for a UI component confirms that the component renders without throwing; it does not confirm what the user sees. The author's observation from Module 7: *"a failing screenshot is more convincing than a passing unit test."* Visual regressions — text overflow at mobile viewport, a font loading failure, a z-index collision — are invisible to test suites that never render the DOM.
## Agent Definition (Canonical Form)
```markdown
---
name: ui-verifier
model: claude-sonnet-4-6
tools: Read, Bash(npx playwright:*), chrome-mcp
---
For each UI change in the diff:
1. Identify the affected route(s).
2. Use chrome-mcp to load each route in three viewports
(mobile 375px, tablet 768px, desktop 1440px).
3. Capture screenshots.
4. Inspect for: clipped text, overflow, missing fonts, broken
contrast, console errors.
5. Report any issues with screenshot reference.
```
## Standard Viewport Set
| Viewport | Width | Represents |
| -------- | ------ | --------------------- |
| Mobile | 375 px | iPhone SE / small Android |
| Tablet | 768 px | iPad portrait |
| Desktop | 1440px | Laptop / wide monitor |
Extending to 320 px (small feature phones) or 2560 px (4K) is optional and context-dependent.
## Integration Pattern
Wire the UI Verifier as a step in the same [[Builder-Critic Pattern]] pipeline as functional review, but gate it on a path filter — run it only when `git diff --name-only` includes files under the frontend source tree (e.g., `src/ui/`, `src/components/`, `pages/`). This avoids spending browser-launch overhead on backend-only diffs.
## Relation to Headless Agent in CI
[[Headless Agent in CI]] covers the general pattern of non-interactive CLI agent invocations in GitHub Actions, including prompt flags, max-turns caps, and bypass procedures. The UI Verifier Agent is a specific instantiation of that pattern, with the added tool surface of `chrome-mcp` or Playwright and a visual inspection task rather than a code-review task.
## Limitations
- Cannot detect semantic regressions (e.g., wrong data displayed) without a reference screenshot or assertions on DOM content.
- Requires a running dev server or preview deployment in the CI environment.
- Screenshot comparison is subjective when no reference baseline exists; the agent's visual inspection substitutes for pixel-diff tooling when a baseline is not maintained.
## Related
- [[Headless Agent in CI]]
- [[Builder-Critic Pattern]]
- [[Verifier Independence]]
- [[Specialized Agent]]
## Sources
- [[Modern AI Software Engineering - The Orchestrators Playbook]]