visual-qa
Use vision models to self-review screenshots against design intent. Catches spacing issues, alignment problems, color inconsistencies, responsive bugs, and accessibility gaps. Use when reviewing designs, comparing implementations to mockups, or doing pre-ship QA.
dylanfeltus · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add dylanfeltus/skills --skill visual-qaAbout this skill
name: visual-qa description: Use vision models to self-review screenshots against design intent. Catches spacing issues, alignment problems, color inconsistencies, responsive bugs, and accessibility gaps. Use when reviewing designs, comparing implementations to mockups, or doing pre-ship 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
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 pos
Read the complete source ↗