| name | visual-audit |
| description | Screenshot and analyze visual composition: golden ratio, rule of thirds, spacing, hierarchy. Verify UI quality before presenting. |
Visual Audit
Screenshot a website and analyze its visual composition against established design principles.
When to Use
- After building or significantly modifying a frontend component/page
- When the user asks to check how something looks
- Before presenting UI work as complete
Workflow
- Determine the URL -- dev server, usually
localhost:<port>. Check running processes or ask the user.
- Run the audit script:
python3 ~/Claude/scripts/visual-audit/audit.py <url> [--width 1920] [--height 1080] [--full-page]
- Read the generated images using the Read tool:
- Read
original.png first to see the actual rendered page
- Read
full-overlay.png to see the design grid analysis
- Optionally read
golden-ratio.png for focused golden ratio analysis
- Analyze against the visual audit checklist below
- Report findings with annotated image paths and a text summary of issues
Visual Audit Checklist
- Golden Ratio Alignment -- Do key elements (hero, CTA, images) align with golden ratio intersections?
- Spacing Consistency -- Are margins/padding consistent between similar elements?
- Visual Hierarchy -- Is importance communicated through size, weight, color, position?
- Whitespace Balance -- Is negative space distributed intentionally, not randomly?
- Contrast & Readability -- Is text readable? Sufficient contrast between elements?
- Composition Flow -- Does the eye follow a natural path (ideally along the golden spiral)?
- Alignment -- Are elements that should be aligned actually aligned?
- Responsive Concerns -- At this viewport, does anything overflow, collapse, or look cramped?
Report Format
## Visual Audit: [page/component name]
**Screenshots:** [paths to generated images]
### Findings
- [specific observation with location reference]
- [specific observation with location reference]
### Suggestions
- [actionable fix with specificity]
Important Notes
- Always screenshot BEFORE making changes so you can compare before/after
- If the dev server is not running, do not start one without asking
- Multiple viewport sizes are useful for responsive checks:
- Desktop: 1920x1080
- Tablet: 768x1024
- Mobile: 375x812
- The overlay images are guides, not gospel -- visual design is subjective, use them to inform analysis not dictate it
