Computational Marketing
FeaturesLong read

A branding agency that writes your brand into BRAND.md and DESIGN.md: what a technical buyer should test before trusting brand files as the deliverable

Four tests show whether brand files hold real decisions or just mood.

· 8 min read
Cover illustration for “A branding agency that writes your brand into BRAND.md and DESIGN.md: what a technical buyer should test before trusting brand files as the deliverable”
Features · November 21, 2026 · 8 min read · 1,859 words

A branding agency can write a useful, AI-readable brand identity into BRAND.md and DESIGN.md. But two Markdown files are not, by themselves, a complete branding engagement. A technical buyer should test whether they encode real decisions, work outside the agency’s tools, and support consistent production over time. The distinction is between documents that describe a brand and inputs that a team can reliably build with.

What BRAND.md and DESIGN.md actually are, and why the format exists

DESIGN.md is a plain Markdown document that gives AI agents a design system they can read directly, while a PDF or Figma export needs a person to make sense of it. Google Labs built the format inside its AI design tool Stitch, then open-sourced the specification. It combines token values in YAML frontmatter or interleaved YAML blocks with design rationale in prose. BRAND.md extends the idea to positioning, messaging pillars, voice rules, audience definition, and ideal customer profile language.

DESIGN.md sits at a project root beside README.md, but putting it there does not make every agent read it. Claude Code needs a reference in CLAUDE.md, and Cursor needs a rule that points to the file. The purpose is to constrain the model’s choices. A fixed palette, type scale, and set of voice rules still leave room for layout and writing, but set limits on both.

Why a thin file — adjectives and hex codes — passes for a complete deliverable

The same container can hold a full brand system or almost nothing. Both arrive with the expected filenames and readable headings. A DESIGN.md full of visual descriptions, but missing exact hex, rem, ms, and radius values, still leaves an agent guessing at concrete decisions. It is a mood board in disguise. Likewise, “bold, approachable, data-driven” tells a model how to sound without explaining what distinguishes the business.

That gap can be hard to spot at handover because well-written prose looks like it has been thought through. Vercel’s engineering team found that different models read the same prose about visual language in very different ways. The team rebuilt its approach around prose guidance, a public stylesheet, and deterministic code checks, though outputs still did not fully converge. Markdown’s appearance gives no reliable measure of its completeness.

Test 1: Whether the design tokens are machine-consumable, not just human-readable

Diagram: Five Token Groups a Machine-Consumable DESIGN.md Must Define. Visualizes: A credible DESIGN.md defines exactly five structural token groups that engineers need: (1) Colors — hex values and usage roles; (2) Typography — family, weight…

Start with the values an engineer would otherwise have to invent. A credible DESIGN.md defines five structural token groups, including colors, typography, spacing, border radii, and motion. Colors need hex values and usage roles, while typography needs family, weight, size, line-height, and tracking for each role. Spacing needs a base unit and a name for each step in the scale. Radii should be tied to component types, and motion should have exact values in place of ranges or adjectives.

Does their naming convention follow the Design Tokens Community Group format, and can engineers transform them with Style Dictionary into Tailwind, CSS custom properties, or a component library? Readable YAML is not the same as a demonstrated conversion path. Ask whether the file is paired with a Figma library with published variables as the authoritative source of truth. Without that source, there is no agreed value to sync from when the design system changes.

Then ask an agent to build a landing-page section from the delivered file. Generic SaaS output is a warning that the constraints are too weak. Vercel held the prompt, model, and viewport constant in a renewal-proposal comparison. Adding design.md changed not just styling but hierarchy, leading with the recommendation and grouping commercial evidence on a shared scale.

Test 2: Whether BRAND.md encodes real strategic decisions or just surface tone

BRAND.md must explain why a buyer should choose the brand even alongside a technically sound DESIGN.md, and that requires more than voice adjectives. Can the file answer “why this brand, not its nearest competitor”? The positioning statement should name both the category and the differentiator. Its messaging pillars should make specific, falsifiable claims that a competitor could not plausibly adopt unchanged.

The audience definition needs similar depth. An ideal customer profile should cover language patterns and key objections as well as demographics. Was it based on sales-call notes, lost-deal analysis, and investor objections, or only executive interviews? Real customer language gives the agency something firmer than internal preference to encode.

Voice rules need a test of their own. Ask for a “do / do not” example pair for each rule, specific to the brand. If the examples could belong to any company, the rule is decorative. Also ask what accompanies the file, such as usage examples, sales-deck templates, and handover documentation. Those materials show how to turn strategic choices into guidance that people can use without having to work out what the statements mean.

Test 3: Whether the files work outside the agency's own toolchain

The portability promise rests on plain Markdown that an agent can read without a proprietary schema or a special build step. VoltAgent’s awesome-design-md repository demonstrates the approach with files usable across tools including Cursor, Claude Code, and Windsurf. Agent configuration may still be necessary, but access to the agency’s private environment should not be.

The acceptance test is a controlled comparison. Take the delivered files into a tool the agency did not configure, such as Claude Code, Cursor, or a fresh Stitch session. Run the same build prompt. If output degrades significantly, ask which dependencies or instructions were present in the original environment. A file that relies on sibling files the agency has not handed over is incomplete.

Dependencies can be legitimate if they are accessible. Vercel publishes design.md at a public URL and pairs it with a public stylesheet containing design-system primitives that any page can load. Ask whether the proposed package has a stylesheet or component-library reference that is just as stable, or relies on a local file tree that the agency controls. If it includes a Brand Context MCP server, confirm ownership and hosting before counting that service as part of the handover.

Test 4: Whether the brand language in the files is structured to be cited by AI answer engines

Portability shows whether another agent can build with the files. It does not answer whether an AI answer engine can find and cite the brand. A prospective buyer asking what tools a GTM team uses for a task may encounter a cited answer. If the brand is missing from that answer, it misses that chance to reach the buyer. This makes the language destined for external surfaces a separate part of the deliverable.

Ask which prompts the target buyers are likely to type into ChatGPT, Claude, Gemini, and Perplexity. Then ask how BRAND.md prepares claims for extraction in response to those questions. Specific, verifiable statements with named evidence give a retrieval system something to surface. Aspirational adjectives do not serve the same purpose. A platform-agnostic file is not, on its own, a generative engine optimization strategy, because citation patterns can differ sharply between engines.

External consistency is part of this test. The brand’s name, description, founding context, and service category should match across its website, LinkedIn, Crunchbase, G2, and relevant industry directories. Conflicting versions leave room for confused answers. Ask whether entity-consistent language for those surfaces is a named output of the engagement, rather than an assumed consequence of rewriting the website. For AI visibility, a well-written private file is only an input to the work.

Test 5: Whether the files can power a multi-stage content pipeline with human review gates

Once the language is ready, the next question is operational. Can the buyer’s content pipeline consume BRAND.md as a stable, versioned input? Ask the agency for an example parameterized prompt template stored in version control that uses the file. A free-form prompt typed into a chat window does not show that the pipeline can use the file in that way. Ad-hoc prompts leave the pipeline without a dependable basis for testing, comparing changes, or auditing its instructions.

The production workflow needs three distinct stages. Automated consistency checks can test the language patterns, prohibited phrases, and voice rules that the brand sets out. Human editorial review must handle judgment calls that the file cannot encode, including whether a piece sounds like the brand. Post-publish monitoring then connects what was published with what AI engines subsequently cite.

Ask the agency to document that division of responsibility. Which decisions can the files automate, and which require human sign-off? The file should reduce the reviewer’s burden. Without an explicit boundary, a seemingly automated process can remain manual in practice. A deliverable that cannot enter this workflow remains a reference document.

Test 6: Whether the engagement includes a governance and freshness plan for the files

A production pipeline makes stale guidance more consequential. Suppose a team wires BRAND.md into its workflow, then changes pricing or faces a new competitor. If no revision is triggered, the pipeline keeps generating copy for the old positioning. Its consistency becomes part of the problem.

Identify the owner of updates and the triggers for revision. A product launch, messaging test, or a lost-deal pattern that keeps coming up can each be a sign that the file needs attention. Updates should be versioned so that the pipeline can roll back a change that degrades output quality. The ownership needs to be explicit, whether it stays with the agency or moves inside the buyer’s team. A handover date is not an update process.

A Brand Context MCP server gives agents another way to get the current brand system, through a live source they can query. But even with up-to-date access, someone still has to keep the brand decisions up to date. Handover documentation, including component guidelines and examples of how to use them, also helps new team members and new agent contexts make sense of those decisions. An engagement that ends with two files leaves responsibility after delivery unresolved.

What a complete, credible markdown brand deliverable looks like

A credible package makes its decisions inspectable. DESIGN.md contains named YAML token values for colors, typography, spacing, radii, and elevation, with exact motion guidance and a Figma library of published variables as the authoritative source. BRAND.md records positioning, customer language and objections, and voice rules demonstrated through “do / do not” examples. These files make the discovery work available to agents and engineers.

Prompt templates kept in version control link the files to production, while written review gates spell out which checks are automatic and which need editorial judgment. Entity-consistent language and an extraction plan connect the brand to external answer engines. A named owner, revision triggers, and versioning govern changes, with a live MCP source available as a way to distribute the current state. Together, these elements define what the agency is handing over and what the buyer must maintain.

Before accepting delivery, running the portability comparison in a tool the agency did not configure provides the fastest proxy for hidden context. A large gap between environments gives the buyer a concrete reason to ask what is missing, rather than debating whether the documents look thorough. The purchasing decision should turn on what the package enables the team to do without the agency silently filling in the blanks.

More in Features