You get a Slack message: "the button is two pixels off." A screenshot is attached. You spend the next three minutes trying to describe the misalignment to your AI assistant in words, then give up and fix it yourself. Sound familiar?
Claude Code has been able to read images for a while now, but I find that most developers I talk to have not actually folded it into their daily flow. I was the same way—convinced that a careful written description would be more reliable than tossing in a picture. Once I switched to pasting screenshots first and writing instructions second, my UI fix turnaround dropped to roughly a third of what it used to be.
This article is not a generic Vision API rundown. It is the workflow I use, every day, in a real terminal, to ship UI fixes faster, along with the gotchas I had to discover the hard way.
Why a Screenshot Beats a Paragraph
Visual bugs encode information that does not survive translation to prose. To describe "the search field below the menu button has its focus ring missing on the left and right edges," you have to spell out coordinates, states, and styles. A single screenshot tells Claude all of this in one frame: layout, color, spacing, typography, even font rendering quirks.
The gain shows up most strongly in problems that are obvious by eye but tedious to articulate—layout drift, contrast issues, broken responsive behavior, font fallbacks. For those, the time-to-merged-fix shrinks dramatically when you stop typing descriptions.
There is a secondary benefit that surprised me. Once your team gets used to dropping screenshots into Claude Code, the bug reports themselves get better. People stop writing prose ("the thing is broken on mobile") and start attaching the actual frame. The whole feedback loop tightens, not just the AI step.
Three Ways to Hand an Image to Claude Code
Claude Code lives in your terminal, so the question is mechanical: how do bytes of an image actually reach the model? Three options work reliably in practice.
Option 1: Paste from Clipboard
On macOS, capture with Shift + Command + Control + 4 to copy a screenshot to the clipboard, then press Control + V in the Claude Code prompt. Most Linux terminals behave the same. WSL on Windows is hit or miss depending on the terminal emulator—if you live there, prefer the file-path method below.
A successful paste shows a placeholder like [Image #1]. Add your instruction text on the next line and send.
[Image #1]
In the top-right card, the title and icon are vertically misaligned.
Open src/components/StatCard.tsx and fix the flex align-items setting.Notice how short the instruction can be—the screenshot already says "this card, this misalignment." This is the option I reach for first whenever a teammate shares a screenshot in chat. There is no need to save the file anywhere; the bytes go straight from clipboard to model.
Option 2: Reference by File Path
Save the screenshot inside your project (for example screenshots/header-misalign.png) and reference it directly:
Use @screenshots/header-misalign.png as the target appearance.
Update src/components/Header.tsx so the header matches:
- logo height 32px
- horizontal padding 24pxThis is my preferred path when working with Figma exports or with screenshots that an E2E test produced on failure. You get a permanent artifact in the repo, and the prompt itself reads like a clear bug report. It also gives you a referenceable record after the PR ships—six months later, you can find the original target frame in git rather than digging through Slack history.
For the broader "design comp to code" flow, see Implementing landing pages from Figma comps with Claude Code.
Option 3: Send from the IDE Extension
The VS Code and JetBrains extensions both let you right-click an image file and send it directly to Claude Code. When I am already in the IDE, this is the path I take—no context switch back to the terminal. The extension setup is covered in Boosting productivity with the Claude Code VS Code extension.
One nuance worth knowing: the extension respects whatever directory permissions you have configured in settings.json. If you have whitelisted only certain folders for image input, sending an out-of-scope image silently does nothing. I have spent more than one minute confused by this exact behavior.
Prompt Templates That Hold Up in Practice
The minute after the paste is where quality is won or lost. Two templates I keep coming back to:
Template 1: Hand Over "Current" and "Target" as Two Images
[Image #1] ← current implementation
[Image #2] ← Figma target comp
#1 is what we ship today. #2 is what we should ship.
The deltas I have spotted:
- card vertical gap (current 8px / target 16px)
- button corner radius (current 4px / target 8px)
- icon stroke weight
Edit src/components/PricingCard.tsx. Use Tailwind utility classes only.The extra step of listing the deltas in writing makes a real difference in fix accuracy. If you just paste the two images and say "make it match," you tend to get drive-by changes to unrelated areas in the diff. The model is very good at spotting differences—maybe too good. By naming only the deltas you actually care about, you keep the diff focused.
Template 2: Pair an Error Screen with Your Hypothesis
[Image #1] ← Sentry error screen from production
This only fires in production. Reading the trace, signWebhook in
src/lib/payment.ts seems to be hitting an undefined crypto.subtle.
Locally we run on Node so this never trips. Cloudflare Workers
exposes a different crypto API—please diagnose and propose a
patch that works on Workers.Sentry, DataDog, and similar tools have their own visual layout that matters. Pasting their screenshots verbatim is faster than reformatting the stack trace into Markdown. Including your own hypothesis is also worth its weight in tokens—it gives the model an anchor and lets it agree, refine, or disagree with a concrete starting point rather than starting from nothing.
Three Pitfalls That Bit Me
The following are the unglamorous gotchas I learned the hard way.
First, accidentally feeding sensitive material to the model. A screenshot from a customer support session containing real PII is one careless Control + V away. I keep a _screenshots/ directory at the project root, list it in .gitignore, and use Claude Code permissions to allow image input only from that directory. Anything outside that folder requires explicit approval, which gives me a half-second to think before I send. The permissions side of this is covered well in The practical guide to Claude Code hooks for 2026.
Second, resolution and token cost. A raw 5K Retina screenshot is a non-trivial number of input tokens. For layout review, downscaling to roughly 1280px wide preserves enough detail and keeps the bill sensible. I have sips -Z 1280 input.png --out resized.png aliased in my shell, and I run it before pasting any image larger than the viewport I am actually debugging. The visible quality loss is zero for UI work; the cost difference adds up fast across a workday.
Third, assuming the screenshot replaces the instruction. Vision is good, but it is not a mind reader. If you do not name the file or component to edit, Claude has to guess, which produces messier diffs. Naming the target—"src/components/Header.tsx"—is a five-character investment that pays back constantly. When the image is ambiguous about scope (a full-page screenshot of an app where only one section needs fixing), pointing at the file is the difference between a clean three-line patch and a sprawling refactor.
The mechanics of Claude's vision capabilities themselves are worth a quick read in The Claude Vision capabilities guide.
When Not to Use Image Input
For all the wins, image input is not the right tool every time. If the bug is in business logic—an off-by-one in a date calculation, a wrong rounding mode in pricing—a screenshot adds nothing the unit test would not show better. Same with refactors: when the goal is restructuring rather than visual change, written intent and code excerpts beat any picture.
I have also learned to skip image input when iterating quickly on a single component. The first paste is high-leverage; pasting a fresh screenshot for every two-line change wastes tokens and slows the loop. Once Claude has the visual context for a component, follow-up turns can stay text-only until something visually surprising happens.
A useful rule of thumb: if a teammate could understand the bug from the words alone, words are probably enough. If they would say "can you send me a screenshot," that is your cue to paste.
A Single Action for Tomorrow
On your next UI bug, replace the written description with a pasted screenshot for one ticket. That is it. Once you feel the gap between "describe in words" and "show the picture" close, the rest of your flow will shift on its own. The team conventions—where to keep screenshots, what to put in the .gitignore, which prompt template to standardize—will fall into place naturally once the muscle memory of "paste, then type" is in place.