To use multiple design references with Claude Code, give each reference one job, decide which wins when they disagree, and keep your own design system above all of them. Three references with clear roles (one for layout, one for density, one for type) produce a coherent result. Three references handed over as “make it like these” produce an average of three products, which usually looks like none of them.
If you’re working with a single reference, the basics are in how to give Claude Code visual design references. This article is about what changes when there are several.
Why multiple references go wrong
- Blending: the agent averages qualities that only work together in their original context.
- Silent conflicts: one reference is airy, another dense. The result is neither.
- Surface copying: colours and illustrations from whichever reference is most visually striking leak in.
- Lost hierarchy: without a ranking, the last reference mentioned often wins.
Give every reference one job
Before attaching anything, decide what each reference is for, in one line. Useful jobs are narrow:
- Composition: where things sit and how sections relate.
- Density: row heights, padding, how much fits.
- Typography: size and weight relationships, not the specific font.
- A pattern: how one component behaves, such as filters or an empty state.
- A counter-example: what to avoid, and why.
If two references have the same job, keep the better one. Redundant references add weight without adding information.
Write a reference brief
A short table in the prompt does most of the work:
Build the activity page. References in refs/activity/:
| Ref | Job | Take | Ignore |
| --- | --- | --- | --- |
| A-layout.png | composition | day groups with sticky date headers | colours, icons |
| B-density.png | density | 36px rows, muted timestamps | type, layout |
| C-type.png | typography | weight contrast between actor and action | everything else |
| D-avoid.png | counter-example | AVOID: avatar + card per event | |
Priority when they conflict: our design system > B > A > C.
Everything visual (colour, fonts, radii) comes from our tokens.
Before coding, describe the page in one paragraph and name which
reference each decision came from.The final line is the important check. If the agent can’t attribute a decision to a reference or to your system, it probably came from a default.
Rank them, and put your system first
Conflicts are inevitable. Decide the order before they happen. A practical precedence for product work:
- Accessibility and function.
- Your design system: components and tokens.
- Project rules you’ve written down.
- References, in the order you ranked them.
Writing that order into your CLAUDE.md means you don’t restate it for every task.
Resolve conflicts explicitly
When two references pull in different directions, ask the agent to surface the conflict rather than split the difference:
A suggests generous spacing between day groups; B's rows are tight.
Don't average them. Give me two options: (1) B's row density with
A's spacing between groups, (2) B's density throughout. Screenshot
both at 1440px.Comparing options built on purpose is a lot more useful than a blend. The same principle applied to whole directions is in how to explore multiple UI design directions.
Check attribution in the result
After the build, verify each reference did its job and nothing else:
Screenshot the activity page. For each reference, list what in the
result came from it. Then list anything in the result that came from
none of them or from our system, and anything that looks borrowed
from a reference's "ignore" column.How many references is too many?
There’s no fixed number, but each reference costs context and attention. In practice, two to four per task, each with a distinct job, is easier to control than six. If you need more, split the work: references for the layout pass, others for the typography pass.
When references come from a library
The reference brief above is easiest to write when references already carry their reasons. A library organised by design attribute, with notes on what to take and ignore, turns the brief into a selection rather than a writing exercise; see how to build a design inspiration library.
Attuna, in private beta, works this way. References are saved with notes and tagged by attribute (typography, layout, density and so on), attached to a project, and readable by Claude Code over MCP. The project’s rules sit alongside them, and accessibility and function always rank first.