Visual QA — Screenshot Issue Detector
When to Use
ALWAYS run visual-qa after taking any screenshot during UI development or testing. This is non-negotiable — it catches the issues you miss while focused on your specific task.
Trigger on:
- Any
agent-browser screenshot call
- User says "check the UI", "audit the interface", "what's wrong with this"
- After building or modifying any HTML/CSS/UI code
- Before committing UI changes
How to Use
Quick Review (most common)
# Take screenshot
agent-browser screenshot /tmp/ui-check.png
# Run visual QA via the photon
photon cli visual-qa review --image /tmp/ui-check.png
Before/After Comparison
# Take before screenshot
agent-browser screenshot /tmp/before.png
# ... make changes ...
# Take after screenshot
agent-browser screenshot /tmp/after.png
# Compare
photon cli visual-qa compare --before /tmp/before.png --after /tmp/after.png
Check Setup
photon cli visual-qa status
Reading the Output
The review returns a markdown report with:
- Score (0-100): A = 90+, B = 75+, C = 60+, D = 40+, F = below 40
- Issues sorted by severity:
- 🔴 CRITICAL — must fix before committing
- 🟡 WARNING — should fix, noticeable to users
- 🔵 INFO — minor, nice to fix
Issue Categories
| Category |
What It Catches |
| LAYOUT |
Overlapping elements, broken grids, overflow, clipping |
| CONTENT |
Empty areas, placeholder text, truncated text, missing icons |
| TYPOGRAPHY |
Inconsistent fonts, unreadable text, wrong weight |
| CONTRAST |
Low contrast, clashing colors, elements blending in |
| INTERACTIVE |
Buttons not looking clickable, unclear affordances |
| SPACING |
Inconsistent padding, misalignment, crowding |
| RESPONSIVE |
Wrong sizing, horizontal scroll, unfilled space |
| EMPTY_STATE |
Missing empty state messages, blank unexplained panels |
| CONSISTENCY |
Mixed UI patterns, inconsistent styles |
| ACCESSIBILITY |
Missing labels, color-only indicators, tiny targets |
How It Works
- Runs Qwen3-VL-8B locally via MLX on Apple Silicon
- ~5 GB model, inference takes 15-45 seconds per screenshot
- No API calls, no cost, no data leaves the machine
- First run downloads the model (~5 GB one-time)
Workflow Integration
When you get the issue list back:
- Critical issues: Fix immediately before proceeding
- Warnings: Fix if they're in the area you're working on
- Info: Note for later, don't block current work
- New issues from compare: These are regressions YOU introduced — fix them
Do NOT ignore the output. The whole point is to catch what you miss.
Prerequisites
pip install -U mlx-vlm # One-time setup
The model downloads automatically on first use.
1---2name: visual-qa3description: Automated visual UI issue detection from screenshots. Use EVERY TIME you take a screenshot with agent-browser during UI development. Runs local Qwen3-VL model on Apple Silicon — zero API cost. Catches layout bugs, contrast issues, missing content, alignment problems, and accessibility violations that you'd otherwise miss while focused on one specific fix.4---56# Visual QA — Screenshot Issue Detector78## When to Use910**ALWAYS** run visual-qa after taking any screenshot during UI development or testing. This is non-negotiable — it catches the issues you miss while focused on your specific task.1112Trigger on:13- Any `agent-browser screenshot` call14- User says "check the UI", "audit the interface", "what's wrong with this"15- After building or modifying any HTML/CSS/UI code16- Before committing UI changes1718## How to Use1920### Quick Review (most common)2122```bash23# Take screenshot24agent-browser screenshot /tmp/ui-check.png2526# Run visual QA via the photon27photon cli visual-qa review --image /tmp/ui-check.png28```2930### Before/After Comparison3132```bash33# Take before screenshot34agent-browser screenshot /tmp/before.png3536# ... make changes ...3738# Take after screenshot39agent-browser screenshot /tmp/after.png4041# Compare42photon cli visual-qa compare --before /tmp/before.png --after /tmp/after.png43```4445### Check Setup4647```bash48photon cli visual-qa status49```5051## Reading the Output5253The review returns a markdown report with:5455- **Score** (0-100): A = 90+, B = 75+, C = 60+, D = 40+, F = below 4056- **Issues** sorted by severity:57 - 🔴 CRITICAL — must fix before committing58 - 🟡 WARNING — should fix, noticeable to users59 - 🔵 INFO — minor, nice to fix6061## Issue Categories6263| Category | What It Catches |64|----------|----------------|65| LAYOUT | Overlapping elements, broken grids, overflow, clipping |66| CONTENT | Empty areas, placeholder text, truncated text, missing icons |67| TYPOGRAPHY | Inconsistent fonts, unreadable text, wrong weight |68| CONTRAST | Low contrast, clashing colors, elements blending in |69| INTERACTIVE | Buttons not looking clickable, unclear affordances |70| SPACING | Inconsistent padding, misalignment, crowding |71| RESPONSIVE | Wrong sizing, horizontal scroll, unfilled space |72| EMPTY_STATE | Missing empty state messages, blank unexplained panels |73| CONSISTENCY | Mixed UI patterns, inconsistent styles |74| ACCESSIBILITY | Missing labels, color-only indicators, tiny targets |7576## How It Works7778- Runs **Qwen3-VL-8B** locally via MLX on Apple Silicon79- ~5 GB model, inference takes 15-45 seconds per screenshot80- No API calls, no cost, no data leaves the machine81- First run downloads the model (~5 GB one-time)8283## Workflow Integration8485When you get the issue list back:86871. **Critical issues**: Fix immediately before proceeding882. **Warnings**: Fix if they're in the area you're working on893. **Info**: Note for later, don't block current work904. **New issues from compare**: These are regressions YOU introduced — fix them9192Do NOT ignore the output. The whole point is to catch what you miss.9394## Prerequisites9596```bash97pip install -U mlx-vlm # One-time setup98```99100The model downloads automatically on first use.
portel-dev