The Blind Spot: Why Claude Code Can't QA What It Builds

Every workflow in this track is built around one foundational fact: Claude Code cannot see your UI.

It reads files. It runs commands. It parses terminal output. It writes code. But the moment you open a browser and look at what was built, you are perceiving something Claude Code cannot see on its own — rendered pixels. It only perceives pixels you, or a tool, explicitly hand it as an image.

This is not a bug. It is an architectural reality. Understanding it precisely is what separates operators who iterate efficiently from operators who spend hours in unproductive loops.

What Claude Code Actually Perceives

When Claude Code works on your frontend, here is the complete inventory of what it can observe:

File contents. The raw text of your .tsx, .css, .mdx, or any other source file. It sees the code you wrote, not what that code produces.

Terminal output. Build errors, type errors, lint warnings, test results. If tsc says there is a type error, Claude Code sees it. If your Tailwind class silently produces the wrong visual output, Claude Code sees nothing.

Test results. Unit tests, integration tests, snapshot tests. If a snapshot was generated from broken UI, the snapshot is now the "correct" reference and the test passes.

Your descriptions. What you type into the prompt. If you say "the button is too wide," Claude Code has that signal. But it is filtered through your observation, not its own.

That is the complete list. Claude Code has no autonomous channel to a rendered browser viewport — it never observes the rendered page on its own. The only way pixels enter its context is if you (or a tool) explicitly hand them over as an image.

Real Examples: Code-Correct, Visually Broken

This is where the gap becomes concrete. Each of these examples involves code that is syntactically valid, type-safe, and will pass any automated test — yet produces broken or degraded visual output.

z-index stacking. A modal overlay needs z-index: 50. A sticky navbar has z-index: 40. The dropdown menu inside the navbar uses z-index: 100 — which sounds high, but because it is inside a stacking context created by the navbar's transform: translateZ(0), it is actually scoped below the modal. The modal covers the dropdown. Claude Code reads the CSS values and sees numbers that look fine. You open the browser and the menu is invisible behind the overlay.

overflow clipping. A card component uses overflow: hidden to clip its border-radius. A tooltip on a child element gets clipped off entirely. The code is correct. The card renders. The tooltip is gone. Claude Code reads overflow: hidden and understands what it does, but cannot simulate the visual result against the tooltip's absolute positioning.

Font weight on dark backgrounds. You ask Claude Code to add a subtitle under a heading. It uses font-weight: 300 (Tailwind font-light) because it looks elegant in the class name. On a white background in your design mockup, font-light is fine. On the dark slate background your site actually uses, the thin strokes disappear into the background. The text is technically present and readable by a screen reader. You open the browser and it is nearly invisible.

Flex layouts that read correctly but render wrong. A flex container with justify-content: space-between and three children. Claude Code writes it correctly. What it cannot know is that one of those children is a dynamic component that sometimes renders nothing — leaving two children in a space-between layout where they slam to opposite edges with a giant gap between them. The code is correct. The edge case renders broken.

Images with wrong aspect ratios. A profile image is placed in a 40px × 40px circle container. The source image is 800 × 400 — a landscape 2:1 ratio. Without explicit object-fit: cover, the image squashes vertically. Claude Code places the <img> tag correctly and the container dimensions look right. The rendered result is a distorted face.

None of these produce a build error. None of them fail a test. All of them are invisible to Claude Code. All of them are immediately obvious the moment a human looks at the browser.

The Cost of Blind Iteration

Here is what happens when developers do not have a visual QA method and instead try to fix visual issues through Claude Code alone:

You describe the problem in text: "the card header looks cramped"
Claude Code adjusts padding values
You look at the browser — still wrong, or different wrong
You describe again: "now there's too much space on the right side"
Claude Code adjusts margins
You look — getting closer but the font still looks off
You describe: "the text seems thin and hard to read"
Claude Code changes font-weight
You look — the font weight fixed but now the line height is wrong

Five iterations. Ten minutes. A human looking at a rendered screenshot for twenty seconds could have produced a single structured report: wrong padding, wrong margin, font-weight too low, line height too tight — all at once.

The cost compounds further on larger pages. A dashboard with twelve components might have eight visual issues. Describing them one at a time through text, waiting for each fix, reloading each time — this is the workflow that produces hour-long sessions fixing what should take fifteen minutes.

The fix is not to use less Claude Code. The fix is to close the feedback loop with a visual layer.

Three Methods That Close the Gap

This track covers three practical approaches, each with its own tradeoffs:

The Claude Chrome Extension. An extension you install in Chrome that can see the current rendered page and generate structured feedback. You use it in the browser, get findings, and carry those findings to Claude Code. Best for: live single-page inspection during active development.

Screenshot upload to claude.ai. Take a screenshot, upload it to claude.ai (or paste directly into a Claude Code session with image support), ask for a visual audit. No extension needed. Works with any browser, any device, any project. Best for: design comparison, multi-page audits, mobile testing, fallback when the extension is not available.

Computer-use MCP. An MCP server that gives Claude Code the ability to control a browser directly — take screenshots, navigate, click. The highest-integration option. Best for: automated visual regression testing, complex multi-step interactions, when you want the feedback loop to be fully automated.

This lesson focuses on understanding the problem. The next three lessons in this track cover each method in depth.

The Build-See-Fix-Verify Loop

Every effective UI development workflow follows a version of this loop:

Build → See → Fix → Verify

Build. Write the code with Claude Code. Get it to a state where it compiles and renders something.

See. Open the browser (or the screenshot, or the visual audit tool). Look with human eyes or multimodal AI. Identify specific, concrete visual issues. Do not ask Claude Code "does this look right?" — it will read the source code and tell you the code looks correct, because the code probably is correct.

Fix. Give Claude Code a structured, specific list of findings. File paths, component names, what is wrong, what it should look like. Not "it looks off." Exact findings.

Verify. After the fix, look again. Did the specific issues resolve? Did anything new break?

The key discipline is step two. Most operators skip it or do it poorly. They either do not look at all (pure code-based iteration) or they look but describe vaguely ("something feels off"). The visual QA methods in this track are tools that make step two fast, structured, and actionable.

The Exercise

Here is how to feel the blind spot concretely rather than just understand it intellectually.

Ask Claude Code to build a simple card component: a white card with a dark background, an image at the top, a title, a subtitle in a lighter color, and a button at the bottom.
Do not look at the result yet.
Ask Claude Code: "Does this card look visually correct? Is the font weight right for a dark background? Is the image aspect ratio correct? Is the spacing consistent?"
Read what Claude Code says. It will likely tell you the code is correct, the Tailwind classes are appropriate, and the structure looks good. It is reading the code — and the code probably is syntactically fine.
Now open the browser.
Look at the actual rendered card.
Find the issues — there are almost always at least two or three on a first-pass component.

The gap between Claude Code's text-based assessment and what you see in the browser is the gap this track teaches you to close.

Common Mistakes

Asking Claude Code to self-audit visual output. "Does this look right?" will produce a code review, not a visual review. Stop asking this question.

Describing visual issues with adjectives instead of facts. "The spacing feels off" gives Claude Code nothing to work with. "The gap between the card title and the button is 48px but should be 24px" is actionable.

Fixing one issue at a time without a full audit. You fix the font weight. Claude Code adjusts the file. You reload. You notice the line height. Another round trip. Batch your findings before starting to fix.

Trusting snapshot tests as visual truth. Jest snapshots serialize the DOM structure. They catch structural regressions but not visual ones. A snapshot of a visually broken component is just a snapshot of a visually broken component — the test passes forever.

Summary

Claude Code operates in a text-only feedback loop. It can read your source code perfectly. It can run your tests. It can parse your build output. It cannot see a rendered pixel.

This creates a class of bugs that are invisible to automated tooling but immediately apparent to human vision: z-index failures, overflow clips, font weight degradation on dark backgrounds, flex edge cases, aspect ratio distortions. The only way to catch these is to look at the rendered output — with human eyes, a screenshot upload, a browser extension, or computer-use automation.

The build-see-fix-verify loop is the core pattern. The visual QA methods in this track are the tools that make the "see" step fast, structured, and reliable.

What's Next

The next lesson covers the Claude Chrome extension — how to install it, how to prompt it effectively, and the exact handoff pattern that turns its findings into actionable Claude Code instructions. This is the fastest path from "I see a visual issue" to "it is fixed."