Visual QA of UI screenshots using Playwright capture + LLM vision scoring. Scores layout, typography, contrast, spacing, and brand consistency (0-10 each). Persists verdict JSON in .dog/visual/. Use when you need a systematic visual quality check of a running UI.

/dog:visual-verdict — Visual UI Quality Assessment

Captures screenshots via Playwright (Playwright-first principle), evaluates them using LLM vision, and produces a structured JSON verdict with per-dimension scores and issue list.

When to Use

After implementing a new UI component or page
During a design review cycle
Before shipping a UI-heavy feature
When /dog:design-review has been run and you want a quantified score

When NOT to Use

On non-visual features (APIs, CLIs, background jobs)
When no browser-accessible URL is available

Scoring Schema

{
  "url": "https://...",
  "timestamp": "2026-04-15T12:00:00Z",
  "scores": {
    "layout": 0,
    "typography": 0,
    "contrast": 0,
    "spacing": 0,
    "brand_consistency": 0,
    "composite": 0
  },
  "issues": [
    {"severity": "high|medium|low", "dimension": "layout", "description": "..."}
  ],
  "screenshot_path": ".dog/visual/<slug>-<ts>.png"
}

Composite = average of all 5 dimension scores.

Scoring Rubric (per dimension, 0-10)

Score	Meaning
9-10	Excellent — no issues
7-8	Good — minor issues only
5-6	Acceptable — noticeable issues
3-4	Poor — significant issues
0-2	Broken — critical issues

Process

Step 1 — Capture screenshot via Playwright

// Playwright-first: always use browser, never fetch
const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(url, { waitUntil: 'networkidle' });
const screenshotPath = `.dog/visual/${slug}-${ts}.png`;
await page.screenshot({ path: screenshotPath, fullPage: true });
await browser.close();

Step 2 — Encode and evaluate

Encode the screenshot as base64 and pass to LLM vision with the scoring rubric prompt:

"You are a UI design expert. Evaluate this screenshot on 5 dimensions (0-10 each): layout, typography, contrast, spacing, brand_consistency. For each issue found, record: severity (high/medium/low), dimension, and description. Respond with JSON only matching the schema provided."

Step 3 — Compute composite score

composite = round((layout + typography + contrast + spacing + brand_consistency) / 5, 1)

Step 4 — Persist verdict

mkdir -p .dog/visual
# Write verdict JSON
cat > .dog/visual/${slug}-${ts}.json <<EOF
{ "url": "...", "timestamp": "...", "scores": {...}, "issues": [...] }
EOF

Step 5 — Report

Print a summary table:

Visual Verdict: 7.4 / 10
  Layout:            8.0
  Typography:        7.0
  Contrast:          8.0
  Spacing:           7.0
  Brand consistency: 7.0

Issues (2):
  [MEDIUM] typography: Line height too tight in body text
  [LOW]    spacing: Inconsistent padding on mobile breakpoint

Verification

ls .dog/visual/*.json | head -1 | xargs jq .scores.composite

Expected: a number between 0 and 10.

Skill: dog:design-review, dog:browser-testing, dog:playwright-scraping
Command: /dog:design-review, /dog:qa-browser
Agent: e2e-runner

visual-verdict