$visual-verdict

$visual-verdict performs a deterministic comparison between a generated UI and a reference image. It returns JSON containing a 0-100 score, a pass/revise/fail verdict, a list of concrete differences, and fix suggestions for each difference. Below 90 means iteration should continue.

When to use it

• When you need to compare a generated screenshot against a reference image
• When visual accuracy requirements exist for layout, spacing, typography, or component styling
• When you need a definitive pass/fail gate before merging or deploying UI changes
• When a score-based quality signal is needed inside a $ralph or $web-clone loop

Trigger keywords: "visual verdict", "compare screenshot", "visual QA", "check if it matches"

How to invoke

codex
> $visual-verdict reference_images=["design.png"] generated_screenshot="output.png"

codex
> visual verdict — compare current screenshot against designs/header-spec.png

How it works

Loads the reference image(s) and generated screenshot and performs a multi-dimensional comparison. Items compared are layout structure, spacing and padding, typography (font family, weight, size), color values, and visual hierarchy.

Result comes as a single JSON object. 90 or above is pass, below is revise. The differences array lists concrete mismatches like "top navigation spacing is 8px narrower than reference." The suggestions array contains corresponding fix methods for each difference.

Pixel-level diff tools can be used as secondary aids when diagnosing hard-to-spot mismatches, but visual-verdict is the authoritative decision. When run inside a ralph loop, the verdict is recorded in .omx/state/{scope}/ralph-progress.json so the loop acts on that result.

Outputs

{
  "score": 87,
  "verdict": "revise",
  "category_match": true,
  "differences": ["Primary button uses smaller font weight"],
  "suggestions": ["Set primary button font-weight to 600"],
  "reasoning": "Core layout matches but style details still diverge."
}

Related skills

• $frontend-ui-ux — UI creation skill that uses visual-verdict as its iteration gate
• $ultraqa — QA cycle that can include visual-verdict as a quality goal
• $web-clone — cloning workflow that uses visual-verdict for visual accuracy scoring