Skip to content
Blog

How to give Claude Code visual design references

By Attuna ·

To give Claude Code a visual reference, paste a screenshot into the prompt, drag an image into the terminal or give it the file path. That part is easy. What makes the reference useful is telling Claude what to take from it: the spacing, the type hierarchy, the density, the way a component behaves. An image with no explanation leaves the model to guess which of its hundreds of decisions you care about.

Three ways to share an image

The Claude Code common workflows guide lists three methods:

  1. Drag and drop an image into the Claude Code window.
  2. Copy an image and paste it with Ctrl+V (Alt+V on Windows and WSL).
  3. Give a path, for example use /refs/pricing-table.png as a reference.

Paths are the most repeatable option. Keep a refs/ folder in the project (or outside it, if the images shouldn’t be committed) with descriptive file names, and you can point to the same references in every session.

Say what each reference is for

A screenshot of a well-designed page carries layout, type, colour, iconography, copy tone, imagery and brand all at once. If you want only one of those, say so, and say what to ignore. This is the single biggest difference between references that help and references that produce a loose imitation.

Prompt
I'm attaching three references for the new pricing page.

[1] pricing-table-ref.png: take the comparison table structure only.
    Feature rows grouped under small uppercase headings, checkmarks
    aligned to a strict column grid.
[2] plan-header-ref.png: take the plan header layout. Price, one-line
    description, single button, nothing else above the fold.
[3] our-dashboard.png: this is our product. Match its type scale,
    colours, radii and button styles exactly.

Don't copy illustrations, brand colours or copy from [1] or [2].

Notice the last reference. Including a screenshot of your own product, labelled as the source of truth for visual style, stops borrowed patterns from dragging in someone else’s brand.

Useful things to extract

  • Hierarchy: what the eye sees first, second and third.
  • Density: row heights, padding, how much fits on screen.
  • Type: the size and weight relationships, not the specific font.
  • Structure: grid, alignment and grouping.
  • Component behaviour: how a filter bar, table header or empty state is composed.
  • Restraint: what the reference leaves out.

Describe what you can’t see in a still image

Screenshots don’t show motion, hover states, responsive behaviour or what happens when there are 400 rows instead of eight. If those qualities matter, write them down or link to the live page. Claude Code can read URLs you give it, and with the Chrome integration it can open a page, interact with it and take its own screenshots.

Close the loop with a comparison

A reference is most useful when Claude checks its output against it. The Claude Code best practices suggest exactly this for UI: paste the design, implement it, screenshot the result, compare, list differences and fix them.

Prompt
Implement the pricing table from reference [1] using our components.
Then open localhost:3000/pricing, screenshot it at 1440px, and
compare it with [1] for structure only. List the differences in
grouping, alignment and row rhythm, fix them, and show me the
final screenshot.

Manage context

Images take up space in the context window, and so does the conversation around them. A long session with a dozen screenshots and several rounds of corrections gets less reliable over time. A few habits help:

  • Share two to four references for a task, not twenty.
  • Crop to the part that matters instead of sharing a full page.
  • Write down what you learned from a reference in your brief, then start a fresh session with /clear.
  • Keep lasting decisions in CLAUDE.md rather than re-sending the image that inspired them.

When references live outside the project

Most designers don’t keep references in a code repository. They live in a moodboard tool, a folder of screenshots or a Figma page, along with the reasons they were saved. Copying them into every project, and re-explaining why each one matters, doesn’t scale.

This is where MCP helps. An MCP server can expose a reference library to Claude Code as tools it calls when it needs them, so the agent fetches the relevant references for a task instead of you pasting them. If MCP is new to you, start with what MCP means for designers, then read how to use MCP with Claude Code for design work.

It’s the approach we’re taking with Attuna. You save references with notes and annotations on what you like about them. When Claude Code asks for creative direction for a task, it gets the most relevant references and the evidence for why each one applies, and it can fetch the actual images with your notes attached.

References are direction, not a spec

References show intent. They don’t give exact values, and they shouldn’t be copied. For exact values (colours, spacing, components) your agent needs a design system. The difference matters, and we cover it in design references vs design systems. Both feed into the bigger goal of giving your agents your design taste.

Sources