Teaching an AI your brand: the DESIGN.md
A single markdown file can give an AI a persistent, structured understanding of how a brand looks, feels and reads — so every screen it generates lands on-system, not generic. Here's how it works, and how this very page is built from one.
One file that holds token, rule and rationale.
A DESIGN.md is a plain-text description of a brand's visual language, written so an AI agent can act on it. The format was introduced by Google Stitch and is now an open specification.
It sits between two things that don't quite work for a machine. A Figma export says what to use but not why; a brand PDF talks to humans ("approachable yet premium") but is too loose to follow. DESIGN.md keeps token, rule and rationale in one file — specific enough for the next decision, and carrying the reasoning so the AI stays on-system in a case the file never named.
--- # machine-readable tokens name: "KC Fold" colors: primary: "#0000FF" # KC blue — the spine accent: "#E30613" # KC red — CTA only ink: "#101010" paper: "#FFFFFF" typography: display: { fontFamily: Heebo, fontWeight: 900 } rounded: { sm: 3px, pill: 999px } --- ## Do's and Don'ts (the why) - Red is reserved for ONE primary CTA per view. - No purple, no dark theme, no second face.
A Figma export gives you what. A brand PDF gives you vibes. DESIGN.md gives an agent both — and the judgement to stay on-brand off-script.
KC Fold, rendered from its own DESIGN.md.
Everything below is the design system this page describes — drawn with the same tokens an agent would read. White paper, a blue spine, red used once.
Colour & roles
Typography — Heebo + IBM Plex Mono
Components
One red action per view; everything else carries on blue.
This is where a verbatim, approved client testimonial sits in a live deployment — an example component here, quoted exactly and never invented.
Eight ordered sections, after the tokens.
The Google spec pairs a YAML token block with markdown prose in a fixed order — so a linter can check it and an agent always knows where to look.
The atmosphere, mood and one-line brief.
Each role, hex and when to use it.
Families, scale, weight ladder, tracking.
Container, spacing scale, signature grids.
Shadow tokens and surface hierarchy.
Corners, pills, and the fold motifs.
Buttons, cards, nav — with every state.
The guardrails an agent must respect.
The KC file adds three more after the canonical eight — Motion, Content & Voice and an Agent Prompt Guide — which is what fuses the visual system with the verbal and regulatory rules.
One file in a family.
DESIGN.md is the look-and-feel member of a small family of markdown files that configure how an AI works — alongside the standing orders, the long memory and the reusable playbooks. The companion piece walks through the whole set: the files that run an AI practice.
Want an AI that stays on your brand?
Kramer Consulting helps teams turn regulation into capability and put AI to work the right way — fluently, accountably, on-brand.