Visual QA

Visual QA

Use vision models to self-review screenshots against design intent. Catch spacing issues, alignment problems, color inconsistencies, responsive bugs, and accessibility gaps before shipping.

When to Use

• User asks to "review this design" or "check this screenshot"
• After building a page/component, before shipping
• User wants to compare implementation vs mockup/reference
• User asks "does this look right?" or "what's off about this?"
• Automated design QA step in a build workflow

Core Philosophy

• Screenshot first, then critique. Always look at the actual rendered output, not just the code.
• Be specific. "The spacing looks off" is useless. "The gap between the heading and paragraph is 32px but should be 16px based on the surrounding spacing rhythm" is useful.
• Prioritize impact. Not every pixel matters. Focus on what users will actually notice.
• Reference the intent. Compare against design tokens, mockups, or stated design goals.

How to Review

Step 1: Capture the Screenshot

Use one of these methods to get a screenshot:

Via browser tool:

browser: screenshot (captures the current page)

Via node screen capture (if available):

nodes: screen_record

Via Peekaboo (macOS):

exec: peekaboo screenshot

User-provided: The user may paste/attach a screenshot directly.

Step 2: Analyze with Vision

Use the image tool to analyze the screenshot:

image: [path or URL to screenshot]
prompt: "Review this UI screenshot for design quality..."

Step 3: Structured Review

Analyze the screenshot against these categories (in priority order):

Review Categories

1. Layout & Spacing

Check for:

• Consistent spacing rhythm (is everything on the spacing grid?)
• Alignment — are elements that should be aligned actually aligned?
• Padding consistency within similar components
• Container widths and max-widths
• Responsive behavior (if multiple viewport screenshots available)

Common issues:

• Inconsistent padding in cards (e.g., 24px top, 16px sides)
• Elements slightly off-grid (15px instead of 16px)
• Text not aligned with adjacent elements
• Sections with wildly different vertical spacing

2. Typography

Check for:

• Hierarchy — is it clear what's a heading vs body vs caption?
• Line length — body text should be 45–75 characters per line
• Line height — too tight or too loose for the font size?
• Font weight usage — are weights used consistently for the same role?
• Orphans/widows — single words on their own line in headings

Common issues:

• Heading that doesn't look like a heading (weight/size too close to body)
• Body text line length > 80 characters (hard to read)
• Inconsistent heading sizes across sections
• All-caps text without letter-spacing adjustment

3. Color & Contrast

Check for:

• Text/background contrast (does it look readable?)
• Consistent use of brand colors
• Color meaning consistency (is the same blue used for links AND errors?)
• Dark mode issues (if applicable)
• Hover/active state visibility

Common issues:

• Light gray text on white background (contrast fail)
• Primary color used for too many different purposes
• Borders that are nearly invisible
• Status colors that conflict (green for danger, red for success)

4. Visual Hierarchy

Check for:

• Eye flow — where does the eye go first? Is that correct?
• CTA prominence — is the primary action the most visible element?
• Information density — too sparse or too crowded?
• Grouping — are related items visually grouped?
• White space — is it used intentionally or just leftover?

Common issues:

• Two equally prominent CTAs competing for attention
• Important information buried below less important elements
• Sections that feel disconnected from each other
• Dense walls of text without visual breaks