visual-review

Visual Review Loop Protocol

Invoke after UI is built against the design-system bundle. Generation alone can't be trusted — this loop verifies the rendered result against the committed DESIGN.md and fails the build until the bar is met.

The loop

build → boot dev server → rubric pre-filter (cheap, deterministic)
      → axe-core a11y gate (fail-fast)
      → Playwright screenshot @ 375 / 768 / 1440
      → CRITIC scores screenshots vs DESIGN.md rubric
      → triage [Blocker/High/Medium/Nitpick] → write critique-feedback.json
      → coding agent applies fixes → re-run → check exit criteria

Deterministic harness + pluggable critic. The harness/ runner does the identical-for-every-copilot parts (boot, screenshot, axe, rubric pre-filter, emit artifacts). The critic (aesthetic judgment) is either:

• Agent critic (Claude Code): the visual-reviewer agent reads the PNGs directly (a picture is worth 1000 tokens) and scores them.
• Runner critic (any other copilot): the runner calls a vision-LLM (provider, model, key from env) and writes critique-feedback.json.

Same rubric, same gates, same exit criteria — only the critic swaps.

Running it

From the project root: npm run copilot:review (wraps harness/). It:

1. runs the a11y + rubric gates; on failure writes tmp/ui-review/critique-feedback.json and exits non-zero;
2. captures screenshots at the three breakpoints;
3. runs the critic;
4. exits 0 only when all exit criteria pass (vision critic), or after emitting artifacts for the agent critic to judge.

The coding agent reads tmp/ui-review/critique-feedback.json ({passed, critiqueSummary, actionableFixes[]}), applies the fixes, and re-runs. Never hand-wave a failing gate — fix the UI.

The critic rubric (score each; source of truth is DESIGN.md)

Phased, adapted from published design-review agents (OneRedOak, Anthropic frontend-design, shiplightai):

1. Typography — modular scale, real hierarchy, committed pairing (no default fonts).
2. Spacing & layout — 4/8pt rhythm, internal ≤ external spacing, deliberate layout grammar (no lone centered column, no cardocalypse).
3. Color & theme — semantic-token discipline, dominant + sharp accent (not evenly distributed), light/dark parity, no banned gradients.
4. Hierarchy — one primary CTA per screen; attention guided by size/weight/space.
5. States — empty/loading/error/success/focus present for every data component.
6. Anti-slop flags — any Step-3 tell from design-system present ⇒ automatic fail.
7. Domain fit — does it match the archetype/density locked in DESIGN.md.