What a Design Reference Has to Contain for an Agent to Actually Use It

The normal way to give a coding agent design direction is to paste a URL and describe what you like about it. This mostly does not work, and the reason is mechanical rather than a matter of prompt quality.

Why does pasting a link not work?

Because most coding agents cannot see the page. Either the tool has no fetch capability, or it fetches HTML and gets a shell of framework markup with no rendered layout, or it retrieves a text summary that describes the design in words. In all three cases the model writes the component from its priors, and the priors produce the average page.

A written description does not fix this either, because the description is the lossy step. "Clean and modern with good typography" survives into the output as whatever the model already believed those words meant.

What does an agent actually need?

Image bytes in the vision context, at the moment the component is being written. A screenshot lets the model read type scale, spacing rhythm, border weight, shadow softness and colour relationships directly, rather than reconstructing them from an adjective. Everything else is a proxy for that.

Fetched CSS is the interesting middle case. It carries exact values and no composition, so an agent can copy your --radius and still lay the page out badly. Pixels carry the composition.

What makes a reference retrievable in the first place?

The agent has to be able to find it before it can look at it, and the query an agent receives is almost never a company name. It is a feel. "Make it look like a terminal dev tool." That is why swaggin's primary axis is aesthetic style rather than brand, with 14 styles each carrying written visual cues.

Retrieval also has to be cheap. Images are the expensive thing in a context window, so metadata, taxonomy and search are free and unauthenticated in swaggin, and only the full screenshot sets need a licence. An agent can search the whole registry, read captions, decide what is relevant, and only then spend image budget.

How does this work over MCP?

The Model Context Protocol lets an agent call tools directly. swaggin exposes five, deliberately ordered so the expensive one is never called blind:

• list_taxonomy returns the valid style, category, pattern and platform ids. Free.
• search_designs returns matching sites as metadata only, with captions. Free.
• get_site returns one full site record. Free.
• random_inspiration returns a starting point when the brief is open. Free.
• get_screenshots returns the actual images, at most 6 per call. Licensed beyond low-resolution fold previews.

claude mcp add --transport http swaggin https://mcp.swaggin.dev

The shape matters more than the specific server. Any design reference intended for agents needs a cheap metadata layer for deciding and an expensive image layer for looking, with the agent in control of when it crosses between them.

How is this different from Mobbin?

Mobbin is the incumbent and it has an MCP server, which launched before ours. The difference is what comes back from a call. Mobbin's returns structured references for a human to preview in Mobbin's web interface. swaggin's returns the screenshot itself as image bytes in the agent's context.

Does a small curated library beat a large one for this job?

For an agent, often yes, because the constraint is the context window rather than the catalogue. An agent can look at maybe six images before the cost outweighs the benefit. What matters is whether those six are the right six, which is a curation and captioning problem, not a scale problem.

Curated also means something specific here. A human looked at every screenshot and wrote down what is worth stealing, which is what makes the free metadata layer good enough to decide from. That is the honest tradeoff: a much smaller corpus, described much more carefully.

The short version

• A URL is not a reference if the agent cannot render it.
• Descriptions get resolved by the model's priors, which is the problem you were trying to solve.
• Pixels in the vision context, while the component is written, is the requirement.
• Search by feel, because that is the query agents receive.
• Keep metadata cheap and images expensive, and let the agent choose when to cross.