Visual Verdict

Visual Verdict — Structured Visual QA

Compare generated UI screenshots against reference images and return a strict JSON verdict that drives the next edit iteration.

When to Use

• After implementing any UI component, page, or design change
• When verifying visual fidelity against Figma, ASCII mockups, or design specs
• As a gate before marking frontend work complete
• Inside design-taste and frontend-design workflows as verification step

When NOT to Use

• Pure backend/API work with no visual output
• When no reference image exists (use design-taste for initial design instead)

Inputs

| Input | Required | Source | |-------|----------|--------| | Reference image(s) | Yes | Figma screenshot, design mockup, ASCII art render, or prior approved screenshot | | Generated screenshot | Yes | /screenshot skill, Playwright MCP browser_take_screenshot, or manual screenshot | | Category hint | Optional | e.g. dashboard, form, table, marketing, mobile |

Output Contract

Return JSON only with this exact shape:

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

Field Rules

| Field | Type | Description | |-------|------|-------------| | score | int 0-100 | Overall visual fidelity score | | verdict | string | pass (90+), revise (50-89), fail (= 90: verdict is pass`, mark complete

• If score < 90: apply suggestions, re-screenshot, re-run visual-verdict
• If 3+ iterations without passing: escalate to user with full diff history

Debug Visualization

When mismatch diagnosis is hard:

1. Keep visual-verdict as the authoritative decision
2. Use pixel-level diff as a secondary debug aid to localize hotspots
3. Convert hotspots into concrete differences[] and suggestions[]

# If pixelmatch is available:
npx pixelmatch reference.png generated.png diff.png 0.1

Integration Points

| Skill | How Visual Verdict Fits | |-------|------------------------| | design-taste | Run visual-verdict after design-taste generates initial UI | | frontend-design | Verification gate before marking implementation done | | redesign | Before/after comparison for upgrade quality | | /screenshot | Input capture for generated screenshots | | review-changes | Add visual-verdict as pre-commit check for UI changes |

Example: Full Loop

1. User: "Implement the home page from the ASCII mockup"
2. → frontend-design builds the page
3. → /screenshot captures result
4. → visual-verdict compares against ASCII mockup render
5. → Score: 78, verdict: revise
6.    Differences: sidebar width, heading size, card padding
7. → Apply 3 suggestions
8. → /screenshot captures updated result
9. → visual-verdict re-scores
10. → Score: 93, verdict: pass
11. → Done, commit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lucface
• Source: Lucface/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.