What are machine-readable brand guidelines?
Machine-readable brand guidelines are brand rules written in formats AI tools can read directly, such as .md, .json and .css. They are a necessary first step, but being able to read a brand doesn't tell an agent what great looks like in a given situation.
Also called: brand as code, AI brand guidelines.
Why it matters.
A PDF brand book is hard for AI to use: rules hide in layouts, colours sit in images and nothing can be referenced exactly. Writing the brand as Markdown, tokens in .json and styles in .css lets Claude, ChatGPT, Lovable or a coding agent read the same rules without guessing, so this step is needed.
It isn't enough, though. Context isn't direction. An agent that knows the colours and the tone of voice still doesn't know which message to lead with in a renewal email, which proof point fits a CFO or what a strong LinkedIn hook looks like for this company. That comes from the wider production context, examples of good work and direction for each situation.
Example.
How Brail handles it.
Brail syncs in the guidelines you already have, from brand book PDFs and Figma files to existing .md files, and keeps them as versioned .md, .json and .css files that every tool reads in the same current copy. Alongside them sit the audiences, messaging and examples of good work that the rules alone don't give.
Questions people ask.
- Is a brand .md file enough for AI?
- It's a good start for one person in one tool. For a team, someone has to keep every copy current, and the file still doesn't say what great looks like per situation. See is a brand .md file enough for AI?
- Which format should our brand guidelines be in for AI?
- Markdown for rules and voice, .json or .css for design tokens, and HTML for templates. The format matters less than keeping one current version that every tool reads.
- Why does AI still get our brand wrong when it has our guidelines?
- Because guidelines describe the brand, not the job. The AI also needs the audience, the message, examples of good work and the rules for this situation. See situational direction.
Related terms.
- Brand .md file: A brand .md file is a brand's guidelines written in Markdown so AI tools can read them, often named brand.md or kept in a project's knowledge files.
- Design tokens: Design tokens are a brand's visual decisions (colours, type sizes, spacing, radius, shadows) stored as named values, usually in .json or .css, so tools and agents apply exact values instead of guessing.
- Situational direction: Situational direction is the guidance an AI agent needs on top of brand context to do one specific job well.
- Agentic brand system: An agentic brand system is a brand system written so AI agents can follow it as well as people.
- Production context: Production context is everything an AI agent needs to know to produce a specific piece of work: brand and strategy, audiences and messaging, GTM and marketing strategy, plus whatever the piece depends on, such as customer objections, pricing strategy, product features, proof points, competitors and launches.
- Train AI on your brand: You train AI on your brand by giving it the context, examples, assets and rules it needs before it produces anything.