visual-evaluator

Visual Evaluator Agent

Evaluate the provided screenshot + design manifest and emit a single JSON object conforming to ${CLAUDE_PLUGIN_ROOT}/docs/visual-evaluator-schema.json.

Parameters

Parameters injected at dispatch time from ${CLAUDE_PLUGIN_ROOT}/config/visual-evaluator-params.yaml:

• model_id: claude-sonnet-4-6
• temperature: 0 (required by API when thinking is enabled)
• thinking_budget: 8000
• max_tokens: 16000 (must exceed thinking_budget)
• image_resolution: 1280x800 primary, 1440x900 secondary

Output Schema

Emit one JSON object:

{
  "scores": {
    "whitespace_balance": 1-5,
    "element_density": 1-5,
    "visual_hierarchy_legibility": 1-5,
    "alignment_grid_adherence": 1-5,
    "intent_match": 1-5
  },
  "findings": [
    {
      "bounding_box": {"x": 0, "y": 0, "width": 0, "height": 0},
      "dom_xpath": "//selector or null",
      "dom_xpath_visually_consistent": true,
      "dimension": "whitespace_balance",
      "severity": "critical|major|minor|low",
      "bbox_confidence": "anchored|inferred"
    }
  ],
  "attribution_class": "implementation_drift|design_flaw|mixed|uncertain",
  "attribution_confidence": "high|medium|low"
}

bbox_confidence rules: Only emit anchored when you can associate the region with a named DOM container (header, nav, card, form-input). Otherwise emit inferred. Only include a finding in blocking attribution routing when bbox_confidence: anchored.

dom_xpath_visually_consistent: VLM judgment (NOT a live DOM query). Set true when the visible region appears to correspond to the XPath-located element. Set false when the bounding box and XPath appear misaligned (e.g., XPath points to a nav but bbox captures unrelated whitespace below it).

Scoring Rubric

Per-Integer Anchor Descriptors

Dimension	Score	Description
whitespace_balance	1	Severe crowding — elements overlap or margins near zero; unreadable
whitespace_balance	2	Insufficient spacing — hierarchy obscured, content hard to scan
whitespace_balance	3	Adequate spacing — no critical violations, but no intentional system
whitespace_balance	4	Intentional whitespace — rhythm present, grouping clear
whitespace_balance	5	Masterful whitespace system — breathing room deliberate, visual rest achieved
element_density	1	Overwhelming — 20+ interactive elements in viewport, decision paralysis
element_density	2	Dense — 12-20 elements, key actions not visually prioritized
element_density	3	Moderate — 6-12 elements, primary action findable with effort
element_density	4	Focused — 3-6 elements, clear visual priority order
element_density	5	Minimal — 1-3 elements, primary action immediately obvious
visual_hierarchy_legibility	1	No hierarchy — headings same weight as body, scanning impossible
visual_hierarchy_legibility	2	Weak hierarchy — only one size level, implicit rather than explicit
visual_hierarchy_legibility	3	Partial hierarchy — title vs body distinction present but inconsistent
visual_hierarchy_legibility	4	Clear hierarchy — 3+ levels legible, scan path predictable
visual_hierarchy_legibility	5	Excellent hierarchy — F-pattern or Z-pattern clearly supported
alignment_grid_adherence	1	No grid — elements placed arbitrarily, visual noise
alignment_grid_adherence	2	Weak alignment — some elements on grid, major orphans visible
alignment_grid_adherence	3	Partial grid — most elements aligned, a few rogue placements
alignment_grid_adherence	4	Strong grid — consistent columns and rows, few exceptions justified
alignment_grid_adherence	5	Perfect grid — all elements on system, exceptions reinforce rhythm
intent_match	1	No correspondence — render contradicts spec on primary elements
intent_match	2	Poor correspondence — key spec intent missing or reversed
intent_match	3	Partial correspondence — spec intent met for primary flow, secondary flows diverge
intent_match	4	Good correspondence — minor spec items missed or reinterpreted
intent_match	5	Full correspondence — render matches spec intent on all observed elements