Source: [Give AI agents a design reference](https://treenodes.com/articles/design-references-for-ai-agents/) This Markdown version is generated from the public page. Visit the source for interactive examples and full-size visuals. [All writing](https://treenodes.com/articles/) Published 10 August 2026 · Updated 6 September 2026 · Applied AI · 6 min read # Give AI agents a design reference “Make it look modern” leaves too much to guess. Give your coding agent the colours, type, spacing and component rules it needs to build consistently. Written by [Nermien Barakat](https://treenodes.com/articles/by/nermien-barakat/) · Systems & Applied AI Architect ![A woman arranging visual tokens and interface shapes into a coherent design system while an abstract AI agent follows the pattern](https://treenodes.com/assets/articles/design-references-for-ai-agents-hero-treenodes.webp?v=46db7a005ccc) 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](https://treenodes.com/articles/giving-ai-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](https://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. Diagram: Three stacked layers. Bottom: tokens, the raw values for colour, type and spacing. Middle: components, built only from those tokens. Top: rules and reasoning, which govern when each is used. Each layer builds on the one below it. · Rules and reasoning · when each is used, and why · Accent carries chroma in lines and marks, · never as a flood. · Never pure black or pure white. · Components · assembled only from the layer below · Tokens · colour, type, spacing: the raw values · Aa 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 Diagram: Left: without a reference, the same button rendered three times with three different heights, corner radii and stroke weights. Right: with a design reference, the same button rendered three times identically, each drawn from named tokens. · Without a reference · every answer is a fresh guess · three heights, three radii, three weights · With a reference · every answer is a lookup · --radius-md · --space-3 · --color-accent · one height, one radius, one accent 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: 1. **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. 2. **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. 3. **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. 4. **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. Diagram: A four-step pipeline: Source a reference, Adapt it to your brand, Apply it via the agent, Check the output against the rules. What fails the check feeds back into the Adapt step. · 01 · Source · find a real system · 02 · Adapt · make the values yours · 03 · Apply · agent builds from it · Check · against the rules · whatever fails the check goes back into the reference 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](https://treenodes.com/downloads/practice/DESIGN.md) **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](https://treenodes.com/downloads/practice/design-implementation-brief.txt) **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. READING PATH · 3 OF 4 ## Designing an AI system Choose the parts, define the task, give the agent useful context, then apply it to a changing design. [Next: What is Astra, and when would I use it? Apply the approach to a booking migration and follow the decisions when requirements change.](https://treenodes.com/articles/astra-and-the-moment-the-brief-changes/) [View the complete reading path](https://treenodes.com/articles/reading-paths/#ai-system-design) 1. [01 How AI systems fit together](https://treenodes.com/articles/how-ai-systems-fit-together/) 2. [02 Giving AI a job description](https://treenodes.com/articles/giving-ai-a-job-description/) 3. 03 Give AI agents a design reference 4. [04 What is Astra, and when would I use it?](https://treenodes.com/articles/astra-and-the-moment-the-brief-changes/) **REFERENCES AND FURTHER READING — 5 sources** 1. [getdesign.md](https://getdesign.md/) — A catalogue of DESIGN.md references extracted from shipped products — The service that prompted this article. Useful as a source of worked examples, whether or not you adopt any of them directly. 2. [Design Tokens Format Module](https://www.w3.org/community/design-tokens/) — W3C Design Tokens Community Group — Ongoing work toward an interchange format for tokens, which is the layer a machine-readable reference depends on. 3. Design Systems: A Practical Guide to Creating Design Languages — Alla Kholmatova, Smashing Magazine, 2017 — On the distinction this article draws between the values in a system and the rules that make it coherent. 4. [Atomic Design](https://atomicdesign.bradfrost.com/) — Brad Frost, 2016 — The layered way of thinking about interfaces that the anatomy diagram above is a compressed version of. 5. [A perceptual color space for image processing (Oklab)](https://bottosson.github.io/posts/oklab/) — Björn Ottosson, 2020 — Background on why generating ramps in OKLCH keeps the same step of different colour roles at a comparable visual weight.