rubicanjr/visual-verdict

Visual Verdict — Screenshot QA Skill

Pixel-imprecise human eyes miss visual bugs. This skill provides structured, scored visual review using screenshots, returning actionable verdicts rather than vague impressions.

When to Activate

• After a frontend-dev agent implements a UI component or page
• When cloning an external website (pairs with clone-website skill)
• After CSS changes to verify no visual regressions
• When a designer provides a Figma export or reference screenshot
• Before marking any UI task as complete

How It Works

1. Take screenshot of current implementation
2. Load reference (design mockup, Figma export, or previous version)
3. Score against 6 dimensions (0-100 each)
4. Compute weighted total score
5. Issue verdict: PASS (90+) / REVISE (60-89) / FAIL (<60)
6. List concrete mismatches with file + line fix hints
7. Loop: frontend-dev fixes → new screenshot → rescore → repeat until PASS

Prerequisites

• browser-use MCP installed and active (~/.mcp.json)
• Reference image available (Figma PNG export, screenshot, or URL)
• Implementation running (local dev server or deployed URL)

Scoring Dimensions

Dimension Weights

| Dimension | Weight | Description | |-----------|--------|-------------| | Layout accuracy | 0.25 | Positioning, spacing, alignment of all elements | | Typography | 0.15 | Font family, size, weight, line-height, letter-spacing | | Color accuracy | 0.15 | Background, text, border, shadow, gradient colors | | Responsive behavior | 0.15 | Breakpoint transitions, mobile/tablet rendering | | Interactive states | 0.15 | Hover, focus, active, disabled, loading states | | Content completeness | 0.15 | All text, images, icons, labels present |

Weighted Score Formula

total = (layout * 0.25) + (typography * 0.15) + (color * 0.15)
      + (responsive * 0.15) + (interactive * 0.15) + (content * 0.15)

Scoring Each Dimension (0-100)

Layout accuracy

• All elements exactly in position, spacing matches: 90-100
• Minor spacing deviation (< 4px): 75-89
• Noticeable misalignment (4-16px): 50-74
• Layout clearly wrong (columns swapped, elements missing): 0-49

Typography

• Font, size, weight, line-height all match: 90-100
• One attribute off (wrong weight only): 70-89
• Two attributes off: 50-69
• Wrong font family entirely: 0-49

Color accuracy

• All colors within 5% of reference: 90-100
• One element color clearly off: 65-89
• Multiple elements wrong color: 40-64
• Dark/light mode inverted: 0-39

Responsive behavior

• Tested at 3 breakpoints, all correct: 90-100
• One breakpoint breaks layout: 65-89
• Two breakpoints break: 40-64
• Not responsive at all: 0-39

Interactive states

• All states implemented and visible: 90-100
• Missing one minor state (loading): 70-89
• Missing hover or focus: 50-69
• No interactive states at all: 0-49

Content completeness

• All text, images, icons present: 90-100
• One non-critical item missing: 75-89
• One critical item missing (CTA, heading): 50-74
• Multiple items missing: 0-49

Verdict Thresholds

| Verdict | Score | Meaning | |---------|-------|---------| | PASS | 90-100 | Acceptable for production | | REVISE | 60-89 | Needs fixes, not shippable | | FAIL | 0-59 | Major rework required |

Verdict Output Format

## Visual Verdict: [Component/Page Name]

**Score: 85/100 — REVISE**
**Attempt: 2/5**
**Previous score: 72 (+13 this iteration)**

### Dimension Scores
| Dimension | Score | Weight | Weighted | Issues |
|-----------|-------|--------|----------|--------|
| Layout | 92 | 0.25 | 23.0 | Minor padding on mobile |
| Typography | 68 | 0.15 | 10.2 | Wrong font-weight on H2 |
| Color | 96 | 0.15 | 14.4 | - |
| Responsive | 80 | 0.15 | 12.0 | Card grid breaks at 768px |
| Interactive | 82 | 0.15 | 12.3 | Missing hover on CTA |
| Content | 91 | 0.15 | 13.7 | - |
| **TOTAL** | | | **85.6** | |

### Concrete Mismatches (prioritized by impact)

1. **[Typography / HIGH]** H2 hero heading
   Expected: `font-weight: 700`
   Actual: `font-weight: 400` (normal weight)
   Fix: `src/components/Hero.tsx` → add `font-bold` class to `<h2>`

2. **[Responsive / MEDIUM]** Card grid layout
   Expected: 3-column grid collapses at 1024px
   Actual: Collapses at 768px — causes overflow between 768-1024
   Fix: `src/components/CardGrid.tsx` → change `md:grid-cols-3` to `lg:grid-cols-3`

3. **[Interactive / MEDIUM]** Primary CTA button
   Expected: Darker background on hover (`bg-blue-700`)
   Actual: No hover state change
   Fix: `src/components/Hero.tsx` → add `hover:bg-blue-700 transition-colors` to CTA

4. **[Layout / LOW]** Mobile padding
   Expected: 16px horizontal padding on mobile
   Actual: 12px
   Fix: `src/components/Layout.tsx` → change `px-3` to `px-4`

### Next Steps
Fix issues 1-3 above, then call visual-verdict again.
Estimated score after fixes: ~94 (PASS)

Screenshot Workflow with browser-use MCP

Taking the Current Implementation Screenshot

Use browser-use MCP:
1. Navigate to implementation URL (e.g., http://localhost:3000/dashboard)
2. Wait for page fully loaded (no spinners)
3. Take full-page screenshot
4. Save to /tmp/verdict-current-{timestamp}.png

Loading the Reference

Three reference types accepted:

Figma PNG export: Designer exports component/page as PNG at 2x

Reference path: ~/Desktop/designs/dashboard-v2.png

Previous production screenshot: Regression check

Reference path: ~/.claude/benchmarks/screenshots/dashboard-prod.png

Live URL comparison: Compare two running versions

Reference URL A: http://localhost:3000/dashboard (current)
Reference URL B: https://staging.app.com/dashboard (baseline)

Responsive Testing Breakpoints

Always test at these three widths unless told otherwise:

| Name | Width | Target | |------|-------|--------| | Mobile | 375px | iPhone SE | | Tablet | 768px | iPad portrait | | Desktop | 1440px | Standard laptop |

Integration with frontend-dev Agent

The typical iteration loop:

frontend-dev implements component
  → visual-verdict takes screenshot + scores
  → REVISE: sends concrete fix list to frontend-dev
  → frontend-dev applies fixes
  → visual-verdict rescores
  → Repeat until PASS (max 5 iterations)
  → PASS: task marked complete

Iteration Limit

Maximum 5 iterations per component. If PASS is not reached after 5 attempts:

ESCALATION: Visual QA failed after 5 iterations
Component: [name]
Best score achieved: [score]
Blocker: [specific issue that keeps failing]
Recommendation: [designer clarification needed / fundamentally wrong approach]

Integration with clone-website Skill

When cloning an external site, visual-verdict is the quality gate:

1. clone-website skill produces initial implementation
2. visual-verdict screenshots both original and clone
3. Scores similarity across all 6 dimensions
4. REVISE verdict triggers targeted fixes
5. PASS verdict confirms clone is production-ready

Color Comparison Method

Color is compared by extracting computed CSS values and comparing:

Reference color:      #1D4ED8  (rgb 29, 78, 216)
Actual color:         #2563EB  (rgb 37, 99, 235)
Delta E (perceived):  6.2 — noticeable, score -15

Delta E thresholds:

• Delta E < 2: Imperceptible — full score
• Delta E 2-5: Barely noticeable — minor deduction
• Delta E 5-10: Noticeable — moderate deduction
• Delta E > 10: Clearly wrong — major deduction

Typography Extraction

Typography is checked by reading computed styles, not pixels:

// Extract from running implementation
const element = document.querySelector('.hero-title')
const styles = window.getComputedStyle(element)

{
  fontFamily: styles.fontFamily,        // Compare against reference
  fontSize: styles.fontSize,            // "32px" vs expected "36px"
  fontWeight: styles.fontWeight,        // "400" vs expected "700"
  lineHeight: styles.lineHeight,        // "1.5" vs expected "1.25"
  letterSpacing: styles.letterSpacing   // "normal" vs expected "-0.02em"
}

Common Visual Bugs Caught

• Font weight 400 instead of 700 (bold not applying)
• Tailwind class not included in safelist (purged in build)
• Media query breakpoint uses px when rem expected
• Hover state not added after copy-paste from design
• Icon imported but wrong size prop
• Color defined in CSS variable but variable not set in theme
• Padding/margin using px-3 when design shows px-4
• Z-index issue hiding interactive element
• Border-radius value wrong (rounded vs rounded-lg vs rounded-full)
• Line-clamp not applied, text overflows on mobile

Saving Screenshots for Regression History

After a PASS verdict, save the screenshot as the new baseline:

cp /tmp/verdict-current-{timestamp}.png \
   ~/.claude/benchmarks/screenshots/{component-name}-{date}.png

On the next change, this saved screenshot becomes the reference for regression comparison.

---

Remember: A visual that looks "pretty close" in a quick glance often has 3-5 compounding issues that add up to a broken experience. Score it. Trust the number, not the impression.