A design system tells an AI agent what it’s allowed to use: components, tokens and patterns with exact values. Design references tell it what you’re aiming for: the feel, the hierarchy, the level of restraint. An agent with only a design system builds consistent but uninspired screens. An agent with only references builds something that looks like the reference but doesn’t fit your product. Good results need both, with clear rules about which wins.
Inspiration versus implementation rules
The two answer different questions.
- Design system: Which button do I use? What’s the spacing scale? What colour is an error? The answers are exact and reusable, and they should be enforced.
- References: What should this new screen feel like? How dense? Which of several valid layouts? The answers are interpretive, and they guide rather than dictate.
A design system rarely says how to compose a new type of page. References rarely give a hex value you should ship. Each fills the gap the other leaves.
What goes wrong with only one
Only a design system
The agent uses the right components and the right tokens, and still produces the most predictable arrangement of them: cards in a grid, everything given equal weight. It’s correct and forgettable. This is a common outcome even in well-systematised codebases, because the system constrains the pieces, not the composition.
Only references
The agent imitates the surface of the reference: its colours, its font, its illustration style. Borrowed details clash with your product, and the agent may introduce new one-off values to match. You get visual drift dressed up as inspiration.
When to use each
- Extending existing UI: the design system leads. References are rarely needed.
- A new kind of screen: references lead the composition, and the system supplies every value.
- A new product or rebrand: references lead, and the output becomes the seed of a new system.
- Polishing generated UI: the system catches drift; references set the bar for hierarchy and density.
How they work together
State the precedence explicitly. Agents can’t resolve a conflict between a reference and a rule unless you tell them which matters more.
## References and the design system
- References show intent: hierarchy, density, composition, restraint.
- The design system defines every value: components, colour, type,
spacing and radius. Always use it, even when a reference differs.
- If a reference needs something the system doesn't have, stop and
propose an addition. Don't create one-off values.Then, for each task, say what each reference contributes:
Build the team activity feed.
Reference [1]: take the grouping by day and the muted timestamps.
Reference [2]: take how little decoration each row has.
Everything visual comes from our components and tokens.The mechanics of sharing references are in how to give Claude Code visual design references, and the rules side in how to make Claude Code follow your design system.
Practical examples for product teams
A settings page in a mature product
The system covers almost everything: forms, sections, buttons. One reference for how a well-made settings page handles destructive actions is enough.
A first analytics view
There’s no existing pattern for charts or dense tables. Two or three references set the density and hierarchy, and the agent maps them onto existing tokens, proposing any missing components for review.
A marketing page for a product launch
References carry more weight here: tone, rhythm, imagery. The system still supplies type, colour and buttons, so the page reads as the same product.
Taste sits between the two
There’s a third layer: your principles. They aren’t exact values like a system, and they aren’t examples like references. They’re the reasons behind your choices: prefer weight over size for hierarchy, avoid decorative gradients. They explain why you saved the references and how to apply them. We cover that layer in how to give AI coding agents better design taste.
Attuna keeps these layers separate on purpose. A project’s direction, rules and references live in Attuna, the design system stays in your codebase, and agents reach Attuna over MCP (see what MCP is for designers). For the system side in practice, see design tokens for AI coding agents. For keeping both aligned across a team, see how to keep AI coding agents consistent.