visual-qa git:20260813.6085cf4A

Immutable. This exact content is served forever at /api/v1/blob/aae05c6a7b801028.

---
name: visual-qa
description: Render-first visual quality assurance for frontends, slides, diagrams, SVG/canvas, PDFs, and other visual artifacts. Use whenever Codex creates or changes a visual interface or is asked to review alignment, spacing, typography, connectors, clipping, responsive layout, font fallback, export fidelity, or visual polish. Inspect the actual rendered artifact, measure suspicious geometry, fix visible defects, and re-render before completion.
---

# Visual QA

Source correctness is not visual correctness. Treat the rendered artifact as the test subject.

## Verification loop

1. Define the render matrix: target surfaces, viewport sizes, device-pixel ratios, zoom levels, themes, locales, states, and export formats that matter to the task.
2. Build and open the actual deliverable. Reload after rebuilding, wait for fonts, images, hydration, and layout to settle, and avoid validating a stale cached artifact.
3. Capture and inspect every relevant view. For multi-page or multi-state artifacts, review the complete set rather than a convenient sample.
4. Measure suspicious geometry from the rendered layout. Compare bounding boxes, centers, padding, baselines, and connector endpoints; verify what each connector is intended to connect.
5. Fix the defect at the highest semantic layout layer available.
6. Re-render the affected view, then recheck the complete render matrix for regressions.
7. Report the surfaces and states inspected, the evidence used, and any remaining uncertainty.

Use `$agent-browser` for headless web rendering and interaction. Use `$chrome-cdp` when the task specifically requires the user's visible or authenticated Chrome session and the user has approved it. Render non-web outputs such as PDF or slide exports with their target renderer, convert representative pages to images when useful, and inspect those images. Close browser sessions after the pass.

Read [references/checklist.md](references/checklist.md) before reviewing or handing off an artifact with custom layout, connectors, SVG/canvas, dense typography, CJK text, responsive behavior, or multiple pages/states.

## Evidence model

Use visual inspection and measurements together:

- Screenshots reveal balance, semantics, glyph problems, occlusion, and defects that DOM metrics cannot judge.
- Rendered measurements distinguish real misalignment from visual ambiguity and quantify disputed geometry.
- Source review, successful builds, accessibility snapshots, generic overflow checks, or a single viewport are not proof of visual correctness.

Treat automated warnings as leads. Shadows, transforms, and pseudo-elements can create harmless overflow reports, while a page with no reported overflow can still look wrong.

## Repair hierarchy

Prefer solutions in this order:

1. Use normal flow, Flexbox, Grid, intrinsic sizing, and design tokens for semantic layout.
2. Derive underlines, badges, boxes, and simple decoration from their owning element with borders, backgrounds, or pseudo-elements.
3. Use SVG for genuine vector geometry, charts, and connectors. Derive coordinates from data, anchors, or rendered bounding boxes; use a graph or connector library when routing is non-trivial.
4. Use canvas for high-volume drawing when retained DOM/SVG structure is unsuitable.
5. Use `$imagegen` for raster or illustrative assets. Keep critical text, labels, boxes, and connectors deterministic and code-native; text-rich structural diagrams are not a routine image-generation fallback.

Hard-coded coordinates are legitimate inside stable plots and deliberate vector artwork. They become a defect risk when they duplicate layout facts owned elsewhere. Render and inspect every coordinate-based primitive at its target sizes, and replace fragile coordinates when the shape does not survive that test.

## Completion standard

Finish only after the final artifact itself has been rendered and inspected. A local fix must pass both its focused recheck and a whole-artifact regression pass. Do not claim “pixel-perfect” without screenshot evidence and relevant measurements.