MRBS Specification v1.0

01The Problem

Traditional brand identity systems were designed for human designers. They communicate intent through visual examples, prose descriptions, and spatial diagrams. This works when a designer reads a PDF and applies their judgment — but fails completely when an AI agent needs to create brand-compliant content.

Asset Type	Traditional Format	AI Accessibility
Logo usage rules	PDF pages with visual examples	Cannot parse
Color palette	Designed swatches in PDF	Values extractable, context lost
Typography	Font specimens	Names only, no usage rules
Spacing guidelines	Visual diagrams	Not machine-interpretable
Brand voice	Prose descriptions	Subjective, no validation
Templates	PSD/PPTX/INDD files	Usable but opaque

When you ask an AI agent to "create a presentation following our brand guidelines", it needs structured rules (not prose), validation constraints (what's allowed vs. forbidden), semantic relationships (why colors pair together), contextual rules (different rules for different media), and direct asset access (paths to approved files).

PDF brandbooks cannot provide this. They are designed for human interpretation, not programmatic consumption. MRBS solves this by making brand identity structured, semantic, and machine-accessible.

02Core Principles

MRBS is built on five design principles that guide every aspect of the specification:

01

Semantic over Visual

Describe meaning and intent, not just appearance. A color isn't just a hex value — it has a role, contexts, and pairing rules.

02

Rules as Code

Transform prose guidelines into testable constraints. "Use plenty of white space" becomes structured minimum spacing values.

03

Context-Aware

Different rules for different situations. Formal communications have different voice rules than social media posts.

04

Platform-Agnostic

Works with any AI system, design tool, or platform. No vendor lock-in, no proprietary formats.

05

Human + Machine

Readable by both humans and AI agents. JSON and YAML are chosen specifically because they're structured enough for machines while remaining editable by humans. Brand managers can update files directly; AI agents can parse them programmatically.

03Directory Structure

An MRBS-compliant brand system follows a standardized directory layout. The brand.manifest.json at the root is the entry point — AI agents read this first to discover all available components.

Required Structure

brand-system/
├── brand.manifest.json          # Master index — AI reads this first
├── identity/
│   ├── brand-values.yaml        # Mission, vision, personality
│   ├── voice-tone.yaml          # Writing guidelines by context
│   └── naming.yaml              # Naming conventions
├── visual/
│   ├── colors.tokens.json       # Color definitions + usage rules
│   ├── typography.tokens.json   # Font definitions + scales
│   ├── spacing.tokens.json      # Spacing system
│   └── effects.tokens.json      # Shadows, gradients, borders
├── assets/
│   ├── logos/                   # Logo files + manifest
│   ├── icons/                   # Icon library
│   └── photography/             # Photo guidelines
├── templates/
│   ├── presentation/            # Slide templates + manifest
│   ├── document/                # Document templates
│   └── email/                   # Email templates
├── rules/
│   ├── constraints.yaml         # Do's and don'ts
│   ├── accessibility.yaml       # WCAG requirements
│   └── legal.yaml               # Trademark, disclaimers
└── examples/
    ├── correct/                 # Approved usage examples
    └── incorrect/               # Anti-patterns with explanations

Minimum viable brand: Only brand.manifest.json is strictly required. All other directories are optional — include what you have. The manifest declares which components exist, so AI agents know what to look for without guessing.

04Brand Manifest

The brand.manifest.json is the entry point for all consumers. It contains brand metadata, component paths, and MCP endpoint configuration. AI agents read this file first to understand the brand and discover available resources.

brand.manifest.json

{
  "$schema": "https://mrbs.dev/schema/v1/brand.manifest.json",
  "mrbs_version": "1.0.0",
  "brand": {
    "name": "Acme Corporation",
    "tagline": "Innovation for tomorrow",
    "industry": "Technology",
    "website": "https://acme.example.com"
  },
  "components": {
    "visual": "./visual/",
    "identity": "./identity/",
    "assets": "./assets/",
    "templates": "./templates/",
    "rules": "./rules/"
  },
  "mcp_endpoint": {
    "base_uri": "brand://acme",
    "http_endpoint": "https://registry.example.com/brand/acme/mcp",
    "resources": [
      "brand://acme/manifest",
      "brand://acme/colors",
      "brand://acme/typography",
      "brand://acme/voice",
      "brand://acme/values"
    ]
  }
}

Required fields

mrbs_version — Specification version this brand conforms to
brand.name — Official brand name
components — Paths to at least one component directory

Optional fields

The brand object may include tagline, industry, website, organization, mission, vision, and brand_essence. The mcp_endpoint block is optional but recommended for registry-hosted brands.

05Visual Tokens

Visual tokens define the quantitative aspects of brand identity: colors, typography, spacing, and effects. They follow the W3C Design Tokens format extended with MRBS-specific semantic fields.

Color tokens

Each color is defined with its hex value, semantic role, recommended usage contexts, and prohibited contexts. This enables AI agents to select the right color for the right situation.

colors.tokens.json

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#0066CC",
        "$type": "color",
        "name": "Brand Blue",
        "semantic_role": "brand_identity",
        "description": "Primary brand color for key UI elements",
        "recommended_contexts": ["headings", "cta_buttons", "links"],
        "prohibited_contexts": ["body_text", "large_backgrounds"],
        "pair_with": ["white", "neutral-100"],
        "min_contrast_ratio": 4.5
      }
    }
  }
}

Typography tokens

Typography tokens define font families, weights, sizes, and line heights. Each entry specifies where and how a type style should be applied.

typography.tokens.json

{
  "typography": {
    "families": {
      "display": {
        "$value": "Clash Display",
        "fallback": "sans-serif",
        "use_for": ["headings", "hero_text"],
        "weights": [400, 500, 600, 700]
      },
      "body": {
        "$value": "Plus Jakarta Sans",
        "fallback": "sans-serif",
        "use_for": ["body_text", "ui_labels"],
        "weights": [400, 500, 600, 700]
      }
    }
  }
}

06Identity & Voice

Identity files define the qualitative aspects of a brand: its voice, values, personality, and naming conventions. These are typically YAML or JSON files in the identity/ directory.

Voice & tone

Voice guidelines are structured as explicit attribute arrays with context-specific rules. Instead of prose like "we sound friendly and professional," MRBS encodes what the voice sounds like, what it doesn't sound like, and how it varies by context.

voice-tone.yaml

voice:
  core_attributes:
    - "Professional but approachable"
    - "Confident without arrogance"
    - "Technical yet human"

  sounds_like:
    - "A knowledgeable colleague explaining clearly"
    - "Documentation that answers your questions"

  doesnt_sound_like:
    - "A marketing brochure full of buzzwords"
    - "A gatekeeper making you feel stupid"

contexts:
  formal:
    use_for: ["legal", "investor_relations", "contracts"]
    tone: "authoritative, precise"
    avoid: ["contractions", "colloquialisms"]

  conversational:
    use_for: ["blog", "social_media", "support"]
    tone: "warm, helpful, accessible"
    allow: ["contractions", "questions"]

Brand values

Values are defined with a name, description, and optional visual association (icon color). They help AI agents understand the brand's philosophical foundation, which influences tone, imagery choices, and messaging priorities.

brand-values.yaml

values:
  - name: "Innovation"
    description: "We push boundaries and embrace new approaches"
    priority: 1

  - name: "Transparency"
    description: "We communicate openly and honestly"
    priority: 2

07Rules & Constraints

The rules/ directory encodes brand guidelines as explicit, testable constraints. This is where prose-based "do's and don'ts" become structured rules that AI agents and validation tools can enforce.

Constraints

constraints.yaml

constraints:
  logo:
    minimum_clear_space: "2x logo height"
    minimum_size_px: 32
    prohibited_modifications:
      - "rotate"
      - "stretch"
      - "add_effects"
      - "change_colors"

  color:
    max_brand_colors_per_layout: 3
    require_neutral_background: true
    min_contrast_ratio_text: 4.5
    min_contrast_ratio_large: 3.0

  typography:
    min_body_size_px: 14
    max_font_families_per_page: 2
    prohibited_styles: ["all_caps_body", "underline_for_emphasis"]

Accessibility

MRBS encourages explicit accessibility requirements as part of the brand system. These are defined in accessibility.yaml and can reference WCAG conformance levels, minimum contrast ratios, and required alt-text policies.

Legal

Trademark notices, required disclaimers, and license terms for brand assets are encoded in legal.yaml. This ensures AI agents include required legal text when using brand materials.

08Assets & Logos

Brand assets (logos, icons, photography) are stored in the assets/ directory. Each asset category has a manifest file that describes available variants, approved usage contexts, and file paths.

Logo manifest

assets/logos/manifest.json

{
  "variants": [
    {
      "id": "primary",
      "file": "logo-primary.svg",
      "background": "light",
      "use_for": ["website_header", "documents", "presentations"]
    },
    {
      "id": "reversed",
      "file": "logo-reversed.svg",
      "background": "dark",
      "use_for": ["dark_mode", "photo_overlays"]
    },
    {
      "id": "icon",
      "file": "logo-icon.svg",
      "use_for": ["favicon", "social_avatar", "app_icon"]
    }
  ]
}

By structuring logo variants with explicit context rules, an AI agent can automatically select the right logo for the right situation — dark mode, social media, or print.

09AI Integration

MRBS is designed to be consumed by AI agents via two primary methods: MCP (Model Context Protocol) for real-time access, and system prompt injection for static contexts.

MCP integration

The recommended method. AI tools connect to the brand's MCP endpoint and can query specific resources on demand. See the MCP documentation for setup instructions.

MCP resource URIs

# URI scheme for MRBS resources
brand://{slug}/manifest
brand://{slug}/colors
brand://{slug}/typography
brand://{slug}/voice
brand://{slug}/values
brand://{slug}/rules
brand://{slug}/logos

System prompt integration

For environments without MCP support, brand data can be injected directly into system prompts. The manifest and selected component files are serialized as JSON within the prompt context.

System Prompt Example

## Brand Guidelines

This conversation should follow the MRBS brand guidelines.
The brand identity is defined as:

Brand: Acme Corporation
Voice: Professional but approachable, confident without arrogance
Primary Color: #0066CC (use for headings and CTAs)
Prohibited: All-caps body text, more than 2 font families

// Full JSON can be included for comprehensive guidance

Validation

MRBS files can be validated programmatically against the specification schema. BrandCodex provides a registry endpoint where AI agents can verify color compliance and check brand rules in real time via MCP tools like check_color_compliance.

10Conformance Levels

MRBS defines three conformance levels, allowing brands to adopt the specification incrementally:

Level 1 — Minimum

Basic Identity

Valid brand.manifest.json with brand name and at least one component (colors or voice). Enough for basic AI consumption.

Level 2 — Standard

Complete Visual + Voice

Colors, typography, voice/tone, values, and at least one logo variant. Covers most AI content generation use cases.

Level 3 — Full

Enterprise Ready

All components including templates, rules/constraints, accessibility requirements, legal, and examples (correct + incorrect). Enables autonomous brand compliance validation.

BrandCodex registry requires Level 1 conformance (valid manifest + at least 3 colors or voice attributes) for brand listing, and Level 2 for MCP endpoint activation. Submit your brand to get started.

License

The MRBS specification is released under the Apache 2.0 License. You are free to implement, extend, and distribute MRBS-compliant tooling without restriction. The specification source is maintained at github.com/MRBSystem/MRBS-Specification.