brandbook.md

The landscape

The brand-standards landscape

Several open standards describe brand knowledge in machine-readable form, and a few commercial products build on them. They differ in audience and scope more than in quality; this page compares them honestly so you can pick the right one — including when that is not brandbook.md. Interoperability between these formats is a goal we work towards, not a turf war.

Each entry answers the same five questions: what it is, who maintains it, what it is good at, when to choose it, and where to find it.

brandbook.md (this standard)#

A multi-file governance standard for brand organisations: a folder of Markdown files with YAML frontmatter, a fixed entry point (BRANDBOOK.md) with a typed file index, versioning and freshness metadata, brand hierarchy, and optional content profiles. It is deliberately methodology-agnostic — the structure is normative, the marketing framework is yours — and ships with an opt-in evidence-based profile for teams who want one.

  • Choose it when: a brand organisation (or its agency) needs one maintained source of truth, versioned like software, that both people and AI agents act on across many brands and markets.

brand.md#

  • What it is: a single brand.md file (Markdown with YAML frontmatter) organised in three layers — Strategy, Voice, and Visual — with directory-based hierarchy so product brands can inherit from a master file.
  • Maintainer: Caio Pizzol; open source, MIT, spec v0.2 (early-stage, active).
  • Strengths: the smallest possible artefact that still carries strategy, voice, and visual context; purpose-built to drop into an AI tool’s context the way AGENTS.md serves coding agents. It also scales past a single file: a directory tree of brand.md files lets product brands and sub-brands inherit from a master and override only what differs. Concepts brandbook.md gladly adopted from it: guardrails that merge and never loosen, the ownable test, and an explicit AI-consumption model.
  • Choose it when: the unit of branding is a single project or product — or a family of products and sub-brands that inherit from a shared master via a directory tree — and you want files an LLM can load whole.
  • Links: https://thebrand.md/ (site), https://github.com/caiopizzol/brand.md (spec).

brand.yml#

  • What it is: a single _brand.yml file describing logo, colour (named palette plus semantic roles), and typography.
  • Maintainer: Posit (the Quarto / Shiny / RStudio company); open source, MIT, actively developed.
  • Strengths: mature tooling — a _brand.yml file themes Quarto documents, Shiny apps, and dashboards automatically, with no design work per output.
  • Choose it when: your need is automated visual theming of generated documents and apps, not brand strategy or voice.
  • Link: https://posit-dev.github.io/brand-yml/.

DESIGN.md#

  • What it is: a single file combining YAML frontmatter (machine-readable design tokens — colours, typography, spacing, radii, components) with a Markdown body of human-readable rationale and do/don’t guidance; ships a CLI that lints, diffs, and exports to Tailwind and the W3C token format.
  • Maintainer: Google Labs (the Stitch team); Apache-2.0, alpha, and by a wide margin the most-adopted project in this space.
  • Strengths: strong tooling (accessibility linting, token export) and momentum; a good fit where the deliverable is UI-system fidelity for a coding agent.
  • Choose it when: the primary need is visual and UI-system consistency for AI-assisted interface work, rather than full brand strategy, voice, and governance.
  • Link: https://github.com/google-labs-code/design.md.

brandspec#

  • What it is: a single brand.yaml covering brand essence and voice plus design tokens (colours, typography, spacing) built on the W3C Design Tokens format, with a CLI that generates CSS, Tailwind, Figma tokens, and Style Dictionary output.
  • Maintainer: the brandspec open-source project; MIT, very early and experimental.
  • Strengths: explicit design-token interoperability — it compiles brand definitions straight into code-facing token pipelines.
  • Choose it when: the brand needs to flow into Tailwind / Figma / Style Dictionary tooling, and narrative brand governance is not the priority.
  • Link: https://github.com/brandspec/brandspec.

Brand Context Protocol — one name, three projects#

Three separate efforts ship under the name Brand Context Protocol (BCP), and they are easy to confuse — so each gets a full entry below rather than a shared footnote. In short: one is a published open standard (Encoded Brands), one is a commercial governance platform that presents itself as built on that standard (Aryabhatta Labs), and one is an independent studio’s open methodology sold as an engagement (Wild). Only the first is a format you adopt on your own; the other two are a product and a service, included here because you will meet the name.

Brand Context Protocol — Encoded Brands (brandcontextprotocol.dev)#

  • What it is: a portable brand package published at /.well-known/brand.md on the brand’s own domain — a root Markdown file plus a /.well-known/brand/ subtree (voice, visual, values, boundaries, claims, representation), with an optional JSON manifest, checksums, and design tokens, and defined discovery, resolution, and versioning.
  • Maintainer: Encoded Brands and the community; dual-licensed CC BY 4.0 (spec text) and MIT (schema and reference code); draft v0.5, iterating quickly.
  • Strengths: the only standard here with a domain-level discovery mechanism — third-party agents fetch a brand’s authoritative context from a well-known URL, much as they read robots.txt. Files can be read directly, or served over MCP by a hosted reference registry (registry.brandcontextprotocol.dev) that also cryptographically signs them.
  • Choose it when: you want brand knowledge published at a web-discoverable, versioned location for outside AI agents to fetch, not just a file inside your own repository.
  • Links: https://brandcontextprotocol.dev/ (site), https://github.com/Brand-Context-Protocol/spec (spec).

Brand Context Protocol — Aryabhatta Labs (brandcontextprotocol.com)#

  • What it is: a commercial brand-governance SaaS that sits between AI generation and publication as a “control layer,” checking generated content against brand rules — tone and forbidden words, visual identity, marketing tactics, and claims — inside the tools teams already use, with plugins for Slack, Canva, Zendesk, and MCP clients such as Claude Desktop and ChatGPT, plus a free “Brand X-Ray” audit that scores a site or profile 0–100.
  • Maintainer: Aryabhatta Labs, a product studio. The platform is proprietary but presents itself as built on the open “BCP” JSON standard — the same CC BY 4.0 protocol and registry.brandcontextprotocol.dev registry associated with Encoded Brands. Neither site spells out the corporate relationship between the two.
  • Strengths: enforcement, not just description — it turns brand rules into automated compliance checks that run at the point of content creation across many channels. Freemium and sales-led, with no public pricing.
  • Choose it when: you want a managed product that actively polices AI-generated content for brand compliance inside existing tools, rather than a format you maintain yourself.
  • Link: https://www.brandcontextprotocol.com/.

Brand Context Protocol — Wild (craft.wild.as/bcp)#

  • What it is: an independent take on the same idea from Wild, a Vienna design-and-technology studio — “one place that holds the voice, the design and the rules, written so a person and an AI can both use it,” in four parts (Brand Truth, Skills, Output, Brand Check). The artefact is plain Markdown in your git with light YAML.
  • Maintainer: Wild (Vienna). The structure is deliberately open (“we’re giving it away on purpose,” committed to a GitHub release, forkable and portable); the engagement around it is a paid service. No connection to Encoded Brands or Aryabhatta Labs.
  • Strengths: an opinionated, craft-first methodology delivered as a ~14-week engagement (Brand Truth → live governed system → production skills → measurement) that Wild can also operate for you, with the explicit promise that you own the files and can take them in-house.
  • Choose it when: you want a studio to build and govern the brand-context system with you and hold the quality bar, and you value ownership and portability over running a published standard yourself.
  • Link: https://craft.wild.as/bcp.
  • W3C Design Tokens (https://www.designtokens.org/) — a stable, vendor-agnostic JSON format for design decisions (colour, type, spacing). It carries no brand strategy, voice, or narrative; it is the visual-token layer that brand.yml, brandspec, and DESIGN.md build on. brandbook.md recommends it for assets/files/tokens.json rather than competing with it.
  • llms.txt (https://llmstxt.org/) — a site-level convention for making a website legible to LLMs at inference time. A pattern inspiration for progressive disclosure, not a brand standard.

Converting between standards#

Every format above encodes overlapping knowledge with different fields, so conversion is useful and inherently lossy in the details — a single-file format has no governance metadata to receive, and a visual-token format has nowhere to put a buyer definition. brandsetgo, a companion project of brandbook.md, is planned as a standard-agnostic generator: bring your brand material, pick any supported standard, and get a conforming package out.