BRAND.md

BRAND.md specification

Version 0.1 · Status: draft · github.com/caplifitechnologies/brandmd

v0.1 draft

Abstract

BRAND.md is an open file standard for machine-readable brand identity. It defines a single core markdown file, a folder of deeper files, and a loading protocol that lets any AI agent read a whole brand in under 600 tokens and load detail only when a task needs it. The format is plain text and vendor neutral. It works by paste, attach, or pointer on any platform.

This document uses the keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY as described in RFC 2119. They are normative. Lowercase uses of these words carry their ordinary meaning.

1.File structure

A conformant BRAND.md repository has the following layout.

BRAND.md                  Core file. Repo root. The 600-token brand.
/brand/
  voice.md                Voice, tone, vocabulary, do/don't pairs, banned terms
  visual.md               Full color system, type scale, logo rules, spacing
  strategy.md             Positioning, mission, audience, pillars, differentiation
  usage.md                Channel rules, misuse list, accessibility minimums
  tokens.json             DTCG-format design tokens (W3C Design Tokens spec)
  assets.manifest.json    Every asset file with SHA-256 hash, role, and rules
  /assets/                Logo and mark files (SVG and PNG at minimum)
CHANGELOG.md              Versioned brand history

1.1.A conformant repository MUST contain a BRAND.md file at its root.

1.2.A conformant repository SHOULD contain a /brand/ directory. Files inside it are loaded on demand per the loading protocol in section 3.

1.3.A repository MAY omit any individual /brand/ file. The core file MUST NOT point to a file that does not exist.

1.4.A conformant repository SHOULD contain CHANGELOG.md at its root.

2.BRAND.md core anatomy

2.1.The core file MUST stay at or under 600 tokens, estimated as character count divided by 4. That is roughly 450 words. The core is read in full by every agent on every task, so its size is the standard's central constraint.

2.2.Section order is fixed. A conformant core file MUST present these sections in this order.

# {Brand Name} BRAND.md v{semver}
> {One-line positioning statement}

## Identity
Name, legal name, mission, founded, url, contact.

## Color
Token table: name, hex, role. Six rows maximum in core.

## Type
Display, body, mono. Each with web-safe fallback stack.

## Voice
One line of 3 to 7 attributes. Three do/don't pairs. Banned terms list.

## Logo
File pointers into /brand/assets/ plus the two most important usage rules.

## Load deeper
Map of /brand/ files with a one-line description of when to load each.

## Integrity
Pointer to assets.manifest.json. Spec version. Canonical repo URL.

A core MAY include additional brand-specific sections after Logo.

2.3.The title line MUST carry the brand name and the semantic version, so an agent always knows which brand era it is reading.

2.4.The Color section MUST list at most six rows in the core. A fuller palette belongs in /brand/visual.md.

2.5.Every type entry MUST state a web-safe fallback stack so an agent can render text without the original font file.

3.The loading protocol

This section is normative and is the heart of the standard.

An AI agent encountering a BRAND.md file MUST read it in full. It SHOULD load files from /brand/ only when the task touches that domain: voice.md for writing tasks, visual.md for design tasks, strategy.md for positioning work, usage.md before publishing. Before embedding any asset file, an agent SHOULD verify the file's SHA-256 hash against assets.manifest.json. If a hash does not match, the agent MUST NOT use the asset and SHOULD report the mismatch.

4.Manifest format

4.1.assets.manifest.json describes every asset file in /brand/assets/.

4.2.The manifest MUST be a JSON object with top-level keys version, generated, canonical, and assets.

4.3.Each asset object MUST contain file, sha256 (lowercase hex), role (for example logo-primary, logo-mark, logo-dark), formats (array), and rules (short string).

{
  "version": "0.1.0",
  "generated": "2026-06-12",
  "canonical": "https://github.com/caplifitechnologies/brandmd",
  "assets": [
    {
      "file": "brand/assets/caplifi-monogram.svg",
      "sha256": "f9eab423...98c09e7d",
      "role": "logo-mark",
      "formats": ["svg", "png"],
      "rules": "Never recolor outside the aurora gradient."
    }
  ]
}

5.Tokens

5.1.tokens.json MUST follow the W3C Design Tokens Community Group format (DTCG). Each token is an object with a $value and a $type. Groups nest by dotted path.

5.2.A conformant tokens.json MUST contain a color group and a typography group at minimum.

5.3.This file is the interop bridge to Style Dictionary, Figma, and Tailwind toolchains. Tools that read DTCG tokens read BRAND.md tokens with no translation.

{
  "color": {
    "primary-blue": { "$type": "color", "$value": "#0B3A73" },
    "signal-green": { "$type": "color", "$value": "#54A936" }
  },
  "typography": {
    "display": { "$type": "fontFamily", "$value": ["Michroma", "sans-serif"] },
    "body": { "$type": "fontFamily", "$value": ["IBM Plex Sans", "system-ui", "sans-serif"] }
  }
}

6.Versioning

6.1.A brand version MUST follow semantic versioning. Major: an identity change, for example a new logo or a new palette. Minor: additions that do not change existing identity. Patch: corrections.

6.2.Every release MUST add an entry to CHANGELOG.md.

6.3.The version MUST appear in the BRAND.md title line, as stated in 2.3.

7.Conformance

A tool claims BRAND.md support when it does all of the following.

7.4.A tool that reads the core, honors the protocol, and verifies hashes is a conformant BRAND.md consumer. A tool that writes a repository matching sections 1 through 6 is a conformant BRAND.md producer.

A.License

The BRAND.md specification and the reference site code are released under the MIT license. Brands described with BRAND.md retain all rights to their own content.