Describe a visual bug to an AI coding agent by naming the exact component, its current state, and the value it should have instead, never a feeling. "The spacing looks off" gives the agent nothing to act on. "The gap between the card title and body is 4px; it should be 12px, matching the rest of the stack" gives it an edit to make.
This is a translation problem, not a taste problem. Updated August 2026. This guide works through why visual bugs resist description, what a precise report looks like across six visual categories, and the three kinds of bug that stay hard to put into words no matter how careful you get.
This is part of the wider picture of how to review what your AI coding agent built: the step where your judgment is the only input the agent doesn't already have. A full-resolution screenshot costs about 2,691 tokens for an agent to read on Claude 4.7 and later, calculated from Anthropic's published vision formula — the full token math is here — and it still doesn't say which four pixels you meant or why they're wrong (Source: Anthropic, 2026). Used precisely, words are usually cheaper than the picture, and clearer.
Why are visual bugs the hardest to report?
Visual bugs are hard to report because they're comparative and subjective by default: "off" describes a feeling relative to an expectation only you're holding. A functional bug ships with an error message and a stack trace; a visual bug ships with nothing but your reaction, so the words you choose are the entire bug report.
An agent that gets TypeError: cannot read property 'map' of undefined knows exactly what broke and where. An agent that gets "the header looks weird" knows you're unhappy and nothing else. It has no default visual taste to fall back on, so it either guesses, usually wrong, or asks a clarifying question that costs you another round trip. The pattern is the same one covered in how to give feedback to Claude Code so the fix actually lands: specificity is the only lever you have.
What does the agent actually receive?
An AI coding agent never sees your screen render. It receives text: your sentence, the source code already in its context, and, if you attach one, a screenshot converted into image tokens. It has no felt sense that something is "off." Every ambiguity in what you write becomes ambiguity in what it changes.
That's the deeper mechanism behind why your AI agent can't see what it built: rendering happens somewhere the agent has no access to, so whatever you hand it in words or pixels is the only evidence it has to work from. There's no implicit channel where it absorbs your intent. If a fact isn't in the message, it isn't in the model.
How do you name a location precisely?
Name the component, not the page region: not "the header" but "the card title in the third row of the pricing table," including its state if relevant, like "on hover." If you know the file or component name, include it. A precise name turns a search across the whole UI into a single, targeted edit.
A useful location has four parts, and most reports only include the first:
- The component or section, named as specifically as you can ("the pricing table's middle card," not "the pricing section")
- The state it's in when the bug appears: default, hover, focus, after a click, loading
- The file or component name, if you have it open
- The viewport or window size, if the bug only happens at one size
Skip the last two and the agent has to search the whole codebase to find what you mean before it can even start fixing it.
How do you describe what's wrong versus what you want?
State the current value and the target value as two separate, measurable facts. "The gap is 4px" alone is still incomplete; pair it with "it should be 12px, matching the spacing used elsewhere in the stack." A complaint gives the agent a direction with no destination; a before-and-after gives it both ends of the edit.
The target value doesn't have to be exact. "About twice the gap used on the card above it" is a real target, because the agent can go measure that gap and match it. What breaks reports isn't imprecision, it's a report that's entirely one-sided: all complaint, no destination, or a target with no stated problem to fix.
When is a picture worth the tokens?
A screenshot earns its cost when the bug is a relationship a sentence can't compress: overlapping elements, a layout that's broken in a way you can't name, or a colour that's wrong only in context. For a single, nameable property, like a 4px gap or a wrong hex code, a precise sentence is cheaper and just as exact.
- 2,691 tokens — one full 1080p screenshot (Claude 4.7+; 1,560 on standard tier)
- 1,334 tokens — a smaller, cropped screenshot (1,288×811, measured)
- ~150 tokens — a spoken walkthrough's transcript, typical
Neither screenshot number tells the agent which part of the image you meant or why it's wrong. A screenshot without a location and a target value is still an incomplete report; it's just a more expensive one. The cheapest report is a written sentence precise enough to skip the picture entirely. The most expensive mistake is a screenshot sent on the assumption that pixels speak for themselves. They don't. They still need the same location and target value attached — the same principle behind giving your agent visual feedback without burning tokens: pointing and narrating pairs the pixels with the reason instead of sending one without the other.
What about spacing, colour and motion specifically?
Each category fails for a different reason. Spacing and colour are usually just unmeasured, "off" instead of a pixel or hex value. Alignment and typography get described relatively, not numerically. Motion and state get described as a feeling, not a before-and-after. The fix is always the same: swap the feeling for a number, a token name, or a named state.
Here's the same fix worked across ten real examples, covering spacing, colour, alignment, typography, motion and state:
| What people say | What the agent actually needs |
|---|---|
| "The spacing looks off." | "The gap between the card title and body is 4px; it should match the 12px used elsewhere in the stack." |
| "There's too much padding on that button." | "The button has 24px of horizontal padding; every other button in this file uses 16px." |
| "The blue is wrong." | "The link colour is #3B82F6; the rest of the UI uses #2563EB. Change this one to match." |
| "It doesn't feel dark enough." | "The panel background is #1F2937; drop it to #111827 to match the sidebar." |
| "Things aren't lined up." | "The icon and label are centered against different baselines. Align both to the row's vertical center." |
| "The button's in the wrong place." | "The submit button is left-aligned; it should be right-aligned, flush with the input field above it." |
| "The text is too big." | "The heading is 32px; this level uses 24px everywhere else, and this one should match." |
| "The font looks different here." | "This heading is rendering in the fallback sans-serif, not the site's usual font. Check whether font-family is being overridden." |
| "The animation feels janky." | "The modal's enter transition drops a frame around 100ms in. Try a standard easing curve or a shorter transform distance." |
| "The button doesn't look right when I click it." | "The button's pressed state has no visual change at all. Add a background shift or a slight scale-down on the active state." |
Notice what the right-hand column always has that the left doesn't: a location, a current value, and a target value. That's the whole formula, on repeat.
What's hardest to describe in words, and what do you do instead?
Three categories resist text no matter how precise you get: motion, because it unfolds over time and a still sentence can't carry a curve; state transitions, because the bug only exists in the gap between two states; and viewport-specific bugs, because they only appear at one width. Each needs more than a sentence to survive the trip.
Motion. A sentence can describe a start and an end, but not the curve between them. "The animation feels janky" is a symptom, not a diagnosis — you're detecting something (a dropped frame, a linear ease where a spring was expected, a duration that runs long) without being able to name it from memory alone. Note roughly where in the motion it happens and whether the problem is speed, easing, or a stutter. A short clip settles it in seconds where a paragraph won't.
State transitions. Some bugs only exist between two states: the loading spinner that never clears, the tooltip that stays open after you've clicked elsewhere, the form that shows stale data for one render before catching up. Describing the before and after separately misses the bug, because the bug is the transition itself. Report the exact sequence of actions that triggers it, in order, and what you expected at the moment it didn't happen.
Viewport-specific bugs. A layout correct at 1440px and broken at 768px is invisible unless someone actually resizes the window to that width. "It breaks on mobile" is a hint, not a bug report. Give the exact width, or the breakpoint name if the codebase has one, and describe what happens at that width that doesn't happen above or below it. For the fuller list of what agents miss without eyes on the result, see the "The agent said it's done": 12-point checklist for verifying AI-built UI.
What should you do the next time something looks wrong?
Before you write anything, name the component, its state, the current value, and the value you want, in that order. If the bug is motion, state-based or viewport-specific, add a clip, a repro path, or an exact width instead of relying on a sentence alone. That habit alone fixes more first-try misses than any tool does.
A short checklist for the next report:
- Name the component and its state.
- Write the current value.
- Write the target value, and where it comes from — another component, a design spec, a past version.
- If it's motion, state or viewport-specific, attach a clip or the exact width instead of a longer sentence.
- Send it before you second-guess the wording. A slightly rough report with a real number beats a polished one without.
If pointing at the screen is faster for you than writing the sentence, that's the job Walkie does: you talk while you point, and the agent gets the transcript and the frame instead of a paragraph you had to compose. Either path works. What matters is that the location, the current value and the target value all make the trip.