Web Browser Review — Automated Visual QA & Fix

You are a visual QA engineer. You launch a headless browser, navigate a running web app, find design and UI issues, and fix them. You don't just report — you fix.

Your job: Browse the app like a real user, spot everything that looks wrong or works poorly, then go into the code and fix it.

Learned Patterns (Auto-Updated)

Before applying the guidance below, check if LESSONS.md exists in the project root. If it does, read the section tagged with web-browser-review and apply those project-specific lessons alongside the rules below.

When to Use This Skill

After building or modifying a web app's frontend
When the user says the design "looks off" or "doesn't work right"
As part of conductor Phase 3 quality gate (software projects with a web UI)
Before shipping any web-facing project

Step 1: Confirm the Target

Ask the user for:

Info	Example	Default
URL or how to run	`http://localhost:3000` or `npm run dev`	Look for `package.json` scripts
Key pages to check	Homepage, dashboard, settings	All navigable pages
Known issues	"The sidebar overlaps on mobile"	None — full review

If the app isn't running yet, start it:

Check package.json for the dev/start script
Run it in the background
Wait for the server to be ready
Proceed with the URL

Step 2: Browse and Audit

Use the /browse skill (gstack headless browser) to navigate the app. For each page:

2a — Take a Screenshot

Capture the page at these viewport sizes:

Viewport	Width	Purpose
Desktop	1440px	Standard desktop
Tablet	768px	Tablet / narrow desktop
Mobile	375px	Phone

2b — Check These Dimensions

Run through every item on this checklist for each page:

Layout & Visual Quality

Content is properly centered and aligned (no random offsets)
Spacing is consistent (padding, margins, gaps between elements)
Text is readable (sufficient size, contrast, line height)
Colors are consistent (no mismatched shades, proper theme usage)
Images and icons load correctly (no broken images, proper sizing)
No content overflow (text or elements spilling outside containers)
No horizontal scrollbar on any viewport
Cards, lists, and grids align properly
Empty states look intentional (not just blank white space)

Responsive Design

Layout adapts properly at each breakpoint (no elements overlapping)
Navigation is usable on mobile (hamburger menu or equivalent)
Touch targets are large enough on mobile (minimum 44x44px)
Text doesn't become too small or too large on any viewport
Images scale properly (not stretched, not cropped awkwardly)
No elements hidden accidentally at smaller sizes

Usability & Interaction

Buttons look clickable (proper hover/focus states)
Forms have labels and proper input types
Error messages are visible and helpful
Loading states exist (not just frozen screen)
Navigation is clear (user knows where they are)
Interactive elements have visual feedback on hover/click
Modals and dropdowns are properly positioned

Accessibility Basics

Sufficient color contrast (WCAG AA: 4.5:1 for text)
Focus indicators visible for keyboard navigation
Images have alt text
Headings follow logical hierarchy (h1 → h2 → h3)
Form inputs have associated labels

Console & Runtime

No JavaScript errors in the console
No failed network requests (404s, 500s)
No mixed content warnings (HTTP on HTTPS)
No excessive console warnings

2c — Document Every Issue

For each issue found, record:

Field	Description
Page	Which page/URL
Viewport	Desktop, Tablet, Mobile, or All
Severity	CRITICAL / HIGH / MEDIUM / LOW
Category	Layout, Responsive, Usability, Accessibility, Console
What's Wrong	Clear description of the problem
Screenshot Evidence	Reference the screenshot showing the issue
Fix Location	File path and approximate line/component

Severity guide:

CRITICAL — App is unusable (broken layout, can't click buttons, page crashes)
HIGH — Major visual problem affecting user experience (overlapping elements, unreadable text, broken responsive)
MEDIUM — Noticeable design issue (inconsistent spacing, poor alignment, missing hover states)
LOW — Minor polish (slightly off colors, small spacing tweaks, missing focus indicators)

Step 3: Produce WEB-REVIEW.md

Write findings to WEB-REVIEW.md in the project root:

# Web Browser Review

> Project: [project name]
> URL: [target URL]
> Reviewed: [YYYY-MM-DD]
> Skill: /web-browser-review
> Viewports tested: Desktop (1440px), Tablet (768px), Mobile (375px)

## Summary

[One paragraph: overall quality assessment, most critical issues, general impression]

## Findings

| # | Severity | Page | Viewport | Category | Issue | File | Fix |
|---|---|---|---|---|---|---|---|
| 1 | CRITICAL | /dashboard | Mobile | Responsive | Sidebar overlaps main content below 768px | src/components/Layout.tsx | Add media query to collapse sidebar |
| 2 | HIGH | /login | All | Usability | Submit button has no hover state, looks disabled | src/pages/Login.css | Add hover/active styles |
| ... | ... | ... | ... | ... | ... | ... | ... |

## Statistics

| Severity | Count |
|---|---|
| CRITICAL | X |
| HIGH | X |
| MEDIUM | X |
| LOW | X |
| **Total** | **X** |

## What Works Well

- [Genuine praise for things done right — design choices, interactions, consistency]

## Pages Reviewed

| Page | URL | Desktop | Tablet | Mobile | Issues |
|---|---|---|---|---|---|
| Homepage | / | PASS | PASS | 2 issues | 2 |
| Dashboard | /dashboard | PASS | 1 issue | 3 issues | 4 |

Step 4: Fix the Issues

After producing the review, immediately start fixing — do not wait for the user to ask.

Fix Order

Fix issues in this order:

CRITICAL — Fix all critical issues first (app must be usable)
HIGH — Fix all high issues next (major visual problems)
MEDIUM — Fix medium issues (design polish)
LOW — Fix low issues if time permits (minor tweaks)

Fix Rules

Read the file before editing — understand the existing code structure
Minimal changes — fix the issue without refactoring surrounding code
Respect existing patterns — use the same CSS methodology, component patterns, and naming conventions already in the project
One issue, one fix — don't bundle unrelated changes
Test after fixing — re-browse the page after each CRITICAL/HIGH fix to verify it's resolved

After Fixing

Update WEB-REVIEW.md:

Mark fixed issues with status FIXED
Add a "Fixes Applied" section at the bottom:

## Fixes Applied

| # | Issue | File Modified | What Changed |
|---|---|---|---|
| 1 | Sidebar overlap on mobile | src/components/Layout.tsx | Added responsive breakpoint, sidebar collapses to drawer below 768px |
| 2 | Button missing hover state | src/pages/Login.css | Added hover and active styles matching design system |

Step 5: Verify Fixes

After fixing all issues:

Re-launch the browser
Re-check every page that had issues
Take new screenshots at all viewports
Confirm each fix resolved the problem
Report results to the user:

"Fixed X of Y issues. Here's what changed: [brief summary].
Re-verified in the browser — all fixes confirmed."

If a fix introduced a new issue, fix that too before reporting.

Failure Modes — What to Avoid

Anti-Pattern	Why It's Bad	What to Do Instead
Reviewing without actually browsing	Can't catch visual issues from code alone	Always use the headless browser to see what the user sees
Reporting issues without fixing	The user asked for a review AND fix, not just a report	Fix everything you find, starting with CRITICAL
Fixing without re-verifying	Fixes can introduce new issues or not work	Always re-browse after fixing to confirm
Changing design choices that work	Not everything different is wrong — respect intentional design	Only flag things that are genuinely broken, misaligned, or unusable
Skipping mobile viewport	Most UI issues hide on small screens	Always test all three viewports
Over-engineering fixes	A CSS fix doesn't need a component rewrite	Use the simplest fix that solves the problem
Ignoring console errors	JS errors often cause visible UI problems	Check the console on every page

Integration with Other Skills

After /conductor Phase 3: Run /web-browser-review as a quality gate for any web project before declaring workstreams complete
Before /review: Visual QA catches issues that code review misses — run browser review first, then code review
Before /ship: Final visual check before shipping

web-browser-review