visual-qa

What this skill does

# 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

### 5. Component Quality

**Check for:**
- Button sizing and padding consistency
- Input field styling consistency
- Card styling consistency (shadows, borders, radius)
- Icon sizing and alignment with text
- Image aspect ratios and cropping

**Common issues:**
- Buttons with inconsistent padding or height
- Mixed border-radius values (some 8px, some 12px, some 4px)
- Icons misaligned with adjacent text baselines
- Images stretched or poorly cropped

### 6. Polish & Micro-details

**Check for:**
- Hover states exist and are visible
- Focus states for keyboard navigation
- Loading states (skeleton screens, spinners)
- Empty states (what shows when there's no data?)
- Transitions between states (abrupt vs smooth)
- Favicon and OG image (if reviewing a full page)

**Common issues:**
- No hover state on interactive elements
- Focus ring removed with no replacement
- Abrupt content shifts when data loads
- No empty state — just a blank area

### 7. Responsive Issues (if multiple viewports available)

**Check for:**
- Content readable on mobile (not too small)
- Touch targets ≥ 44px on mobile
- Navigation accessible on small screens
- Images not overflowing containers
- Horizontal scroll (almost always a bug)

---

## Output Format

### Full Review

```
### Visual QA Review

**Overall impression:** [One sentence — first gut reaction]
**Quality score:** [1-10] / 10

#### 🔴 Critical Issues (fix before shipping)
1. **[Category]:** [Specific issue with exact details]
   → **Fix:** [Actionable recommendation]

#### 🟡 Improvements (should fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### 🟢 Minor Polish (nice to fix)
1. **[Category]:** [Specific issue]
   → **Fix:** [Recommendation]

#### ✅ What's Working Well
- [Specific praise — what's well-executed]
- [Another positive]
```

### Quick Review

```
### Quick QA: [Page/Component Name]

Score: [X]/10

Top 3 fixes:
1. [Most impactful issue + fix]
2. [Second issue + fix]
3. [Third issue + fix]

Looks good: [What's working]
```

### Comparison Review (Implementation vs Mockup)

```
### Design vs Implementation Review

**Fidelity score:** [1-10] / 10

#### Deviations Found
1. **[Element]:** Mockup shows [X], implementation has [Y]
   Impact: [High/Medium/Low]
   → **Fix:** [How to match the mockup]

#### Matching Well
- [Elements that accurately match the design]
```

---

## Review Prompts for Vision Model

Use these prompts with the `image` tool depending on what you need:

### General Review
```
Review this UI screenshot for design quality. Check spacing consistency,
typography hierarchy, color contrast, visual hierarchy, and component
quality. Be specific about issues — reference exact elements and suggest
fixes. Prioritize by impact.
```

### Spacing & Layout Focus
```
Analyze the spacing and layout of this UI. Check if elements follow a
consistent spacing grid, if padding within similar components matches,
if alignment is correct, and if the overall spacing rhythm feels right.
Note any elements that appear off-grid or inconsistently spaced.
```

### Comparison Review
```
Compare these two images. The first is the design mockup, the second is
the implementation. Identify every deviation — differences in spacing,
color, typography, alignment, or missing elements. Rate the fidelity
on a 1-10 scale.
```

### Responsive Check
```
Review this mobile screenshot for responsive design quality. Check that
text is readable, touch targets are large enough (≥44px), nothing
overflows the viewport, and the layout adapts well to the narrow width.
```

### Accessibility Focus
```
Review this UI screenshot for visual accessibility. Check text contrast
against backgrounds, focus indicator visibility, touch target sizes,
color-only information (anything that relies solely on color to convey
meaning), and text readability at the shown sizes.
```

---

## Integration with Build Workflow

### After Building a Component

1. Render the component in the browser
2. Take a screenshot
3. Run visual QA review
4. Fix issues
5. Re-screenshot and verify

### After Building a Full Page

1. Screenshot at d