Article Takeaways / TL;DR
- Your brand guidelines now have a second reader: the AI tools your team uses to write and design.
- A PDF explains the brand to people. It doesn’t put the rules in front of an agent while it works, which is why the output comes back almost right.
- The working pattern is two layers: exact values (tokens) and the reasoning behind them (voice, do and don’t, when to bend a rule).
- DESIGN.md and platform instructions like Webflow’s are where that lives. Creating the file is half the job. Getting an agent to actually read and apply it is the other half.
If your team uses AI to draft copy, generate images or build pages, your brand has a reader you never designed for. Your guidelines might explain the brand beautifully in a PDF, but that doesn’t mean those rules are in front of your AI tools when they actually work. So the tools produce something fast, confident and slightly off. The fix isn’t a better PDF. It’s a second version of your guidelines, written so an agent can find and apply the rules while it works.
This builds on why brand guidelines matter as you grow: consistency stops being automatic the moment more than one person or tool produces the brand. An AI tool is just the newest producer, and the one least able to read a document built for human eyes.
Why do your guidelines need a second version?
A brand guideline has one job: let someone who isn’t you produce on-brand work. For a person, a PDF or a web page does that. For an agent, it often doesn’t, because the rules it needs are locked inside a designed layout instead of sitting where the tool can read them as it works. It needs the guidance as structured data and plain language, available in the workflow.
The cost of skipping this is drift. An agent asked to write a landing section or generate a hero image will produce something confident and fast, and slightly wrong: the near-miss blue, a tone that’s a little too casual, a layout that ignores your spacing. Each miss is small. Across a team using these tools every day, they add up to a brand that slowly stops looking like itself, which is the exact problem guidelines exist to prevent.
What does a machine-readable brand file contain?
The pattern that’s settling in has two layers, and every tool below follows it.
The first layer is the exact values: your color codes, type sizes, spacing, corner radii and component styles, written as structured tokens rather than described in prose. This is what lets an agent apply the right hex code instead of guessing a close one.
The second layer is the reasoning. Why those values exist, how the brand should sound with real examples of on-brand and off-brand phrasing, what to do in the cases the tokens don’t cover, and when a rule can bend. This keeps an agent sensible when it hits something the token list never anticipated, like a new component or an awkward layout.
A file with only the first layer leaves the agent to interpret everything the tokens don’t spell out. A file with only the second leaves the exact values open to guesswork. You need both, which is what a good human guideline already has. The task is translating it into a form a machine can read.
DESIGN.md: an emerging format for agent-readable design systems
DESIGN.md is a plain-text file that gives an AI agent a persistent, structured reference for a design system. The agent loads it as context each time it works, rather than carrying it in memory between sessions. Google Labs created the format for its Stitch design tool and open-sourced the draft specification in April 2026. It’s early, and the spec is still labeled alpha, so the details can change. The underlying pattern is already showing up across major tools: Anthropic’s Claude Design, for one, stores brand systems as the same kind of portable markdown file.
It uses the two layers directly. The top of the file holds the design tokens as structured YAML: exact hex codes, font sizes, spacing, radii, component styles. The body is markdown prose that explains the rationale, the brand personality and the guidance that doesn’t reduce to a number, like how much room to give elements or how to handle a case the tokens don’t describe. An agent pulls exact values from the top and uses the prose for the judgment calls, so its output stays on-brand even outside the beaten path.
DESIGN.md centers on the visual-system layer, which is color, type, spacing and components. Voice and messaging don’t naturally live in it. They belong in a companion instruction, like a platform’s own skills or a short summary you paste into a chat tool. DESIGN.md is the visual contract, not the whole brand.
A DESIGN.md is the entry point, not the ceiling, and the design-systems community has been clear about where that ceiling sits. The file is a portable snapshot of intent, not the system itself. It describes the look; the system is what keeps the look consistent as things change. Rename a token or add a component and a hand-maintained file drifts from the real thing, which is why it belongs alongside your full design system rather than in place of it. The tokens layer has a stable, vendor-neutral standard now, the W3C Design Tokens format, which reached its first stable version in late 2025 with backing from more than forty organizations including Adobe, Figma and Google. A mature system keeps those tokens as its canonical source and treats the DESIGN.md as a convenient wrapper over them, so if you already run a real design system, point the agent at the source rather than a summary of it. Figma’s Dev Mode does this directly now, feeding an agent the real variables and components straight from the file. Most businesses aren’t there yet, and a well-kept DESIGN.md is the right first step.
Platform instructions: the layer each platform adds
DESIGN.md is the portable, tool-agnostic layer. On top of it, the platform your team builds in usually adds its own agent instructions, stored with the project so every connected agent inherits them. The shape is converging on two parts: freeform skills for how to approach work, and fixed rules the agent has to follow on every action. You generate a first version from your own site, then review it before switching it on. Webflow is one clear example, and it is not alone. Framer gives its agent the same kind of skills, and Shopify’s theme tooling reads a DESIGN.md directly to carry design intent into new work. The vocabulary differs by platform; the idea is the same.
In Webflow, those two parts are called skills and rules. Skills are freeform guidance on how to approach work, such as your writing style or how to use the design system. Rules are short, fixed criteria that apply to every action an agent takes on the site, like SEO defaults, class-naming conventions or accessibility requirements. You can write them by hand or have Webflow generate them from your own site as Brand Guidelines, Design System, Asset Guidelines or CMS Guidelines. They’re stored with the site and can be shared across a workspace, and they work with Webflow’s own AI as well as third-party agents like Claude connected through its MCP server.
Generating the instructions is the easy part, and it keeps getting easier. Webflow can draft them from your own site, and a recent update lets an agent generate them too. You review and enable the generated skills, but an agent still has to actually read and apply them, and how reliably a third-party tool does that varies. Webflow’s own guidance is to tell the agent to read your site’s instructions at the start of a session, rather than assuming it will. The gap between a rule existing and a rule being applied is the thing to watch, and it only widens as the rules get cheaper to produce.
What this looks like in practice
A token on its own:
primary: #1B4DFF
The same token with the reasoning built in:
primary: #1B4DFF - CTAs and active states only.
Never a background, never decorative. One per screen.
If you’re reaching for a second, reconsider the layout.
That’s the visual layer, and it belongs in a DESIGN.md. Voice doesn’t, and it works the same way, by example rather than adjective:
Voice: direct and specific.
On-brand: “Launch your store with a clear plan.”
Off-brand: “Unlock limitless ecommerce possibilities.”
(Illustrative excerpts, not a full DESIGN.md.)
Then test it. Ask an agent to draft a landing section or a hero image against these rules and check what comes back. That’s how you find the gap between a file the tool can read and one it can follow, before it shows up in live work.
How do you convert your guidelines into something agents can follow?
The work is translation, not reinvention. A rough order:
Pull the exact values out of your guidelines and into structured tokens. Colors, type scale, spacing, radii, named components. If these only exist inside a design file or a PDF, that’s the first gap to close.
Rewrite the rules as short, concrete do and don’t statements, each with a one-line reason. “Keep the logo clear space to at least the height of the mark, so it never reads as crowded” is usable. “Use the logo correctly” is not.
Give voice real examples. A model patterns against examples far better than against adjectives, so include sentences that are on-brand and sentences that aren’t, labeled.
Add component and usage guidance for the situations that actually come up, the same ones that trip up a human vendor: dark backgrounds, co-branding, a layout the system didn’t anticipate.
Keep one short, pasteable summary of the core rules, so someone can drop it into a chat tool that isn’t wired into your stack.
Put each piece where the relevant tool reads it, and confirm it does. A DESIGN.md in the repo, agent instructions in Webflow or your platform of choice, the short summary saved as a tool’s standing instructions. Then run a real task through it, because placement isn’t the same as application.
What this doesn’t replace
None of this removes the person. A machine-readable brand file doesn’t decide what’s right. It makes it faster for people and tools to get close before a human reviews the result. That’s the same line we hold everywhere AI touches our development work: the tool accelerates production, the judgment stays with experienced people. The studios that do this well are the ones who can write both versions, the human guideline and the machine-readable one, because each depends on understanding why the rules exist. Our brand and design work now includes the agent-readable layer for that reason: the tokens, the voice examples, the platform setup and a test task to confirm an agent actually follows it.
Common questions
What is DESIGN.md?
A plain-text file that gives AI agents a structured reference for a design system. It holds exact design tokens in YAML plus plain-language reasoning, so an agent can apply the right values and stay on-brand in cases the tokens don’t cover. Google Labs open-sourced the draft format in April 2026, and it’s still an alpha spec.
Do I need a separate DESIGN.md if my platform already generates agent instructions?
Use what your platform gives you first. Webflow, Framer and Shopify can each generate instructions from your own project. A portable DESIGN.md still helps if you also use chat tools or move between platforms, so the brand travels with you instead of being rebuilt in each one.
Can AI write the brand file for me?
It can draft the structure and pull values, which saves time. The judgment about what the rules are and why still has to come from someone who understands the brand, or the file just encodes the drift you’re trying to prevent.
Does this replace our brand guidelines?
No. It’s a second version of them for a second reader, and it sits alongside the full guideline rather than standing in for it. Keep the human guideline and add the machine-readable one next to it.
Where does this file actually live?
In whatever your tools read. A DESIGN.md in your project repo for coding agents, agent instructions stored on your site for a platform that supports them, a short pasteable summary for chat tools. Most teams end up with more than one, because the brand gets produced in more than one place.
Author:
Jeremy Bokor
Founder, Nifty Inc
