A design inspiration library becomes useful to AI agents when every reference answers two questions: what is this, and why did I save it? Images alone are a moodboard. Images with a written reason, a few consistent tags and a place in a collection are a library that a person or an agent can search by intent, such as “dense tables with good filtering”, and get the right three examples back. This guide covers what to save, how to annotate it, how to organise it, and how to keep it useful as it grows.
Why most inspiration folders don’t help agents
- No reasons. A screenshot of a pricing page doesn’t say whether you saved it for the table, the typography or the tone.
- Inconsistent names. “nice-dashboard-final-2.png” can’t be found by a search for information density.
- Everything at once. Hundreds of references with equal weight give an agent no way to choose.
- Out of reach. A folder on your laptop, a Pinterest board or a Figma page is invisible to a coding agent unless you paste from it.
What to save
Save for specific qualities, not general admiration. A useful library is weighted towards the work you actually do.
- Patterns you’ll build: tables, filters, settings, empty states, onboarding, navigation.
- Craft details: a type pairing, a focus state, a way of grouping metadata.
- Counter-examples: things you deliberately don’t want, with a note on why. These are as useful to an agent as positive references.
- Your own best work: screens from your product that represent the direction.
Crop to the part that matters. A full-page screenshot saved for one table makes the agent guess what you meant.
Annotate: the step that makes it work
One or two sentences per reference, written when you save it. Name the quality, and where relevant what not to take.
Metadata drops to a lighter weight instead of a smaller size, so rows
stay scannable at 40px. Ignore the colour scheme.
Filters collapse into one summary line once applied, with a single
"clear all". This is the behaviour, not the visual style.
Avoid: every card has an icon, a title and two lines. Reads as
template; nothing is prioritised.Annotations are also what make references usable in prompts. The technique for using them with an agent is in how to give Claude Code visual design references.
Tag by design attribute, not by mood
Mood words (“clean”, “premium”, “bold”) describe almost everything and help retrieval very little. Tag by what the reference demonstrates. A small, fixed vocabulary works best:
- Typography
- Layout
- Spacing
- Colour
- Components
- Interactions
- Information density
- Visual hierarchy
Add a second, freer layer for pattern names (pricing table, command menu, onboarding checklist) and product type (B2B dashboard, editorial, mobile). Two or three tags per reference is plenty.
Organise into collections, then into projects
Three levels keep a library navigable as it grows:
- The library: everything you’ve saved, searchable by notes and tags.
- Collections: themed sets you reuse, such as “dense data tables” or “editorial type”.
- Projects: the references that apply to one product, alongside its rules and preferences.
The project level matters most for agents. It answers “which references apply to this work?”, which is the question an agent can’t answer on its own.
Make it reachable by agents
There are three practical ways to get a library in front of a coding agent:
- In the repository. A
refs/folder with annotated file names and a short index file. Simple and versioned, but tied to one codebase. - Pasted per task. Fine for one-offs; doesn’t scale and the reasons get retyped every time.
- Over MCP. A library exposed as tools the agent can search, returning the relevant references with their notes. Works across projects and agents; see what MCP is for designers.
A minimal in-repo index looks like this:
# References
| File | Attributes | Take | Ignore |
| --- | --- | --- | --- |
| table-density.png | density, typography | 40px rows, muted metadata | colours |
| filter-summary.png | interactions | applied filters as one line | visual style |
| avoid-card-grid.png | layout | AVOID: equal-weight card grid | |Keep it useful
- Prune. Remove references that no longer represent the direction. An outdated reference is worse than none.
- Review annotations. If you can’t remember why you saved something, the agent certainly can’t.
- Watch for drift. If your references pull in different directions, decide which wins; see combining multiple design references.
- Respect ownership. References show intent. Don’t ask an agent to copy someone else’s work, and keep borrowed brand elements out of what ships.
A library built for agents
Attuna is a reference library built around these steps. In Attuna, which is in private beta, you save references by pasting or dropping them, add notes, tag them with design attributes (the eight above), and group them into collections. Collections and references attach to projects, and agents that support MCP over HTTP, such as Claude Code, Codex and Cursor, can search them and see the images with your notes. For the wider picture of getting images into agents, see how to give AI coding agents visual context.