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.