Give AI agents a design reference

Ask a coding agent to “make it look modern” and it has to fill in a lot of blanks. Which typeface? How much spacing? Should a button be quiet or prominent? You can end up reviewing a new set of choices on every screen.

A design reference reduces that guesswork. It gives the agent the visual decisions already made for the product, just as a job description gives it a defined task.

What a design reference actually is

A design reference is a written record of visual decisions and the reasoning behind them, in a format a coding agent can read. A catalogue like getdesign.md collects these as DESIGN.md files extracted from real, shipped products: colours, type, spacing, components, and why each is the way it is.

Include the reason behind each rule. A screenshot shows one screen; a rule helps the agent handle a screen you have not designed yet.

Tokens define the values. Component rules explain how to use them.

What one looks like in practice

This site keeps its design rules beside the code. This shortened extract shows the kind of detail an agent can follow:

## Color

Read src/styles/tokens.css for both themes. Use --color-bg
and --color-text for the page, --pg-muted for supporting text.
Keep headings and large surfaces neutral.

Use the shared primary button for the main page action.
Its fill and label use --color-action and --color-on-action.
The header project link is outlined pink; secondary actions
have neutral outlines. Purple marks links and selection.
Green supports diagrams and positive feedback.

## Type

Use the local Inter font through --font-heading and --font-body.
Reuse shared type, spacing and radius rules. Keep paragraphs
within the reading measure and controls easy to tap on phones.

## Don't

- Do not repeat large filled pink actions in one viewport.
- Do not add gradients, glows or new hard-coded colours.
- Do not recolour the logo when changing interface accents.
- Check contrast and layout in both themes.

“Use the spacing variables” is easy to check in a review. “Make it feel clean” still leaves the important choices open.

The difference it makes

A shared reference keeps type, spacing and components consistent across screens.

How to actually use one

Use the reference throughout the change, including the review:

Source it. Take a reference from a real product whose problem resembles yours, or write one from your own brand if you already have tokens. A documentation-heavy fintech is a poor model for a consumer app, and vice versa.
Adapt it. Replace the values with yours while keeping the structure and the rules. This is the step that turns someone else's system into your own.
Apply it. Put the file in the repository, reference it from your agent instructions, and require that new work cites tokens rather than literal values.
Check it. Review the output against the rules, not against taste. "Does this use a ramp step or an invented hex" is a question with an answer.

Update the reference when a design decision changes, then apply it to the affected components.

Adapt the reference to your product

A useful reference may come from another product. Keep the parts that explain how decisions fit together, then choose values and components that suit your audience and brand.

The values are specific. A hue, a spacing unit and a radius belong to a particular brand. Treat them as an example of a coherent choice, not as the choice.
The structure is general. Ramps on a shared lightness scale, named spacing, documented "don'ts": that scaffolding is worth taking wholesale, because it is what makes any set of values checkable.

For TreeNodes, the handoff records our tokens and their intended use. A new page should use those decisions unless there is a reason to change the system itself.

Where it fails

A reference still needs judgement and maintenance:

A reference cannot decide what you are. It encodes a visual language. Choosing which language suits your product is still a positioning decision, and no file makes it for you.
Consistency is not quality. An agent can apply a bad system perfectly. Checkable and good are different properties.
The reference can become outdated. Keep it aligned with the components and tokens in the codebase.

Try it: build from a design reference

Give the agent a screen with a defined job. This reference turns the supplier-review example into a small implementation task while leaving the existing project’s visual identity intact.

How to try it. Add the downloaded DESIGN.md to a test project you can edit, then give your coding agent the prompt below. This is a fictional screen; use a local preview for the exercise.

BEFORE · STATUS ALONE

Cedar Components

Pending

The reviewer still has to find the gap and who should act.

AFTER · A DEFINED HANDOFF

Cedar Components

Status: Needs evidence
Missing: Coverage schedule
Owner: Procurement
Next action: Request the coverage schedule

The design reference

Included file: DESIGN.md

Download file

Full code

# Design reference — fictional supplier review screen

## Purpose
Help an operations reviewer see what is ready, what is missing and who acts next.

## Existing design rules
- Reuse the project's type, colour, spacing and component tokens.
- Keep one page heading, a short introduction and a table or list of cases.
- Show supplier, status, evidence gap, owner and next action for every case.
- Use text labels as well as colour for status.
- Use at least 16px text for phone inputs and 44px targets for primary controls.
- At 390px, stack the case fields instead of shrinking the table's text.
- Preserve visible focus, meaningful labels and reduced-motion preferences.

## Sample cases
- Cedar Components: Needs evidence; coverage schedule missing; owner: Procurement.
- Harbour Supplies: Ready for review; evidence complete; owner: Reviewer.
- Elm Services: Needs evidence; certificate expired; owner: Procurement.

## Boundaries
- This screen prepares a review; it does not approve suppliers.
- Do not invent branding, metrics, testimonials or a working backend.
- Keep existing navigation and the current theme switch.

## Review before handing over
Check 390px and 1280px, both themes, long supplier names and keyboard use.
The next action should still make sense when colour is unavailable.

The implementation brief

Included file: design-implementation-brief.txt

Download file

Full prompt

Build a supplier-review screen using DESIGN.md and the existing project's
components and tokens. Inspect the current page and component patterns first.

Show the three supplied cases with status, evidence gap, owner and next action.
Keep the page useful on a phone and with keyboard navigation. Use fictional local
data; do not add a backend, approvals or invented operating metrics.

Deliver the local screen and a concise note linking each design rule to the
implementation. Check 390px and 1280px, both existing themes, an unusually long
supplier name and keyboard focus. Identify any rule you could not satisfy.
Do not publish the project.

What your result should show

Before: a vague “make it modern” brief leaves the hierarchy and workflow to guesswork. After: each case identifies an owner and a useful next action, with explicit responsive and accessibility rules.
The implementation uses the project’s existing components and tokens. It does not turn “Ready for review” into an approval button or hide status in colour alone.

Change one condition

Replace Cedar with a supplier name twice as long and remove one owner. The layout should still work, and the missing responsibility should be visible rather than silently assigned.

For your next screen, give the agent the reference and ask it to explain any departure from it. Review the result at desktop and mobile sizes, including keyboard use and contrast. A consistent design still has to work for the person using it.

Takeaways

Adapt a relevant reference to your product and brand.
Keep it in the repository and use named tokens in new work.
Check the result on desktop and mobile, including keyboard use and contrast.