Phase 5: Browser-Based Visual QA

This is one of the biggest lessons from the turbulence dashboard build. It fundamentally changed how I work with Claude Code on anything with a UI.

The anti-pattern that cost me hours

Claude Code can take screenshots via Playwright and READ them — it's multimodal. But by default, it tends to run programmatic checks:

Overflow detection
Font size audits
Element counting
DOM structure validation

These checks are necessary but NOT sufficient.

Warning

The actual failure: An audit reported "No overflow detected, All fonts ≥ 12px, Layout structure valid" while the actual screenshot showed tabs overlapping text, header elements competing for space, and a completely unusable mobile layout. The programmatic checks passed. The visual reality was broken.

The fix: visual-first QA

After every Playwright run, Claude Code must:

Capture screenshots at every viewport. Desktop (1920×1080) and mobile (393×852) at minimum. Add tablet if your audience uses them.

VISUALLY INSPECT each screenshot. Actually read the image file. Don't just check if it was captured successfully.

Describe what you SEE. Not what the code checks report. "The header text is truncated at mobile width and overlaps the navigation hamburger icon" is useful. "Layout check passed" is not.

Flag specific issues. Overlaps, truncation, cramped spacing, unreadable text, broken alignment, missing elements.

Never commit CSS changes without visual verification. This is the rule. No exceptions.

Setting up the workflow

Try this prompt

Set up Playwright for visual QA testing. I need:

1. Screenshot capture at 1920x1080 (desktop) and 393x852 (mobile)
2. scrollZoom: true for any chart/interactive content testing
3. Test the following flows:
 - Initial page load
 - Navigation between sections
 - Any interactive elements (modals, dropdowns, tabs)
4. After capturing each screenshot, READ the image file and describe what you see
5. Flag any visual issues: overlaps, truncation, contrast problems, broken layouts

Do NOT just run programmatic checks. I need you to visually inspect every screenshot and narrate your findings.

The explicit instruction to read and narrate is critical. Without it, Claude defaults to programmatic-only checks.

Why this catches 10x more issues than unit tests

Unit tests validate logic. They verify that a function returns the right value, that state updates correctly, that API calls happen in the right order.

But unit tests can't tell you that:

Your chart legend overlaps the data on screens smaller than 1440px
The loading spinner is technically there but invisible against the white background
Your "responsive" table scrolls horizontally but the scroll indicator is hidden
The modal's close button is rendered behind the header's z-index

These are visual bugs, and they're the kind of bugs that make users lose trust. A financial dashboard with overlapping numbers is a financial dashboard nobody will use.

The CLAUDE.md enforcement

I put the visual QA requirement directly in my project's CLAUDE.md file so it applies to every session:

When running Playwright or any visual testing:
- ALWAYS read captured screenshots with the Read tool
- Programmatic checks are necessary but NOT sufficient
- Describe what you SEE in each screenshot
- Flag overlaps, truncation, contrast issues, broken layouts

This turns it from a per-session reminder into a persistent project rule.

Tip

This approach has caught layout regressions that would have shipped to production in every single project I've used it on. It adds maybe 2 minutes per QA cycle. The ROI is enormous.

Next: Case Studies →