# Visual Verdict

> Structured visual QA verdict for screenshot-to-reference comparisons

- Skill: `iml1s/visual-verdict` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iml1s/visual-verdict`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iml1s/visual-verdict/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ImL1s (https://skillmd.com/u/iml1s)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iml1s/visual-verdict

---


## Purpose

Compare generated UI screenshots against one or more reference images and return a strict JSON verdict that can drive the next edit iteration.

## When to use

- The task includes visual fidelity requirements (layout, spacing, typography, component styling)
- You have a generated screenshot and at least one reference image
- You need deterministic pass/fail guidance before continuing edits

## Inputs

- `reference_images[]` (one or more image paths)
- `generated_screenshot` (current output image)
- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)

## Output contract

Return **JSON only** with this exact shape:

```json
{
  "score": 0,
  "verdict": "revise",
  "category_match": false,
  "differences": ["..."],
  "suggestions": ["..."],
  "reasoning": "short explanation"
}
```

Rules:
- `score`: integer 0-100
- `verdict`: short status (`pass`, `revise`, or `fail`)
- `category_match`: `true` when the generated screenshot matches the intended UI category/style
- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
- `suggestions[]`: actionable next edits tied to the differences
- `reasoning`: 1-2 sentence summary

## Threshold and loop

- Target pass threshold is **90+**.
- If `score < 90`, continue editing and rerun `/oh-my-claudecode:visual-verdict` before any further visual review pass.
- Do **not** treat the visual task as complete until the next screenshot clears the threshold.

## Debug visualization

When mismatch diagnosis is hard:

1. Keep `$visual-verdict` as the authoritative decision.
2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.

## Example

```json
{
  "score": 87,
  "verdict": "revise",
  "category_match": true,
  "differences": [
    "Top nav spacing is tighter than reference",
    "Primary button uses smaller font weight"
  ],
  "suggestions": [
    "Increase nav item horizontal padding by 4px",
    "Set primary button font-weight to 600"
  ],
  "reasoning": "Core layout matches, but style details still diverge."
}
```

## Related skills

- **`verify-ui`** — manual screenshot comparison. Use this skill after verify-ui to quantify the diff with image-based metrics.
- **`figma-implement-design`** → **`figma-use`** — after implementing a Figma design, use verify-ui and visual-verdict to validate the implementation matches the reference.
- **`verify-ui-auto`** — after visual-verdict confirms the diff is acceptable, set up automated golden tests to prevent regressions.