A single source of truth for brand

BrandSpec is an open standard for defining a brand as structured, machine-readable JSON. Tokens, strategy, voice, assets, and purpose — all in one canonical file.

A BrandSpec file is a single .json document. Define it once; consume it everywhere.

1. Define your brand

   Create a brandspec.json file using the open schema. Include colours, typography, logos, voice, strategy, and purpose. You can create and manage this in a compatible tool (like the Whyso platform), or write it by hand.

2. Push to your tools

   Feed the file into your design tool, website builder, CMS, or AI. BrandSpec-compatible tools read the tokens and apply them directly — no manual setup, no re-entry.

3. Generate outputs

   Compile BrandSpec tokens to CSS custom properties, Figma Variables, Tailwind config, or any downstream format. The same definition powers every output.

4. Keep it live

   When the brand evolves, update the brandspec.json. Every connected tool stays in sync. Brand drift becomes a configuration problem, not a communications problem.

A BrandSpec document is a JSON object with a root brand key and five top-level sections. All sections are optional at the object level but recommended for complete brand definition.

Colour token fields

Typography token fields

A minimal but complete BrandSpec document. All fields shown are part of the v0.1.0 schema.

{
  "_export": {
    "brandName":        "Example Brand",
    "brandSpecVersion": "0.1.0",
    "exportedAt":       "2026-01-01T00:00:00.000Z"
  },

  "brand": {

    /* ── Tokens ──────────────────────────────── */
    "tokens": {
      "colors": [
        {
          "name":         "Primary",
          "role":         "primary",
          "primarySpace": "rgb",
          "hex":          "#1a1a2e",
          "rgb": { "r": 26,  "g": 26,  "b": 46  },
          "cmyk": { "c": 43, "m": 43, "y": 0,  "k": 82 }
        },
        {
          "name":         "Accent",
          "role":         "accent",
          "primarySpace": "rgb",
          "hex":          "#e94560",
          "rgb": { "r": 233, "g": 69, "b": 96  },
          "cmyk": { "c": 0,  "m": 70, "y": 59, "k": 9  }
        }
      ],
      "typography": [
        {
          "name":       "Headings",
          "role":       "heading",
          "family":     "Plus Jakarta Sans",
          "weights":    [700],
          "fontColor":  "#1a1a2e",
          "lineHeight": "1.2",
          "fallback":   "sans-serif",
          "sizes": { "recommended": 40 }
        },
        {
          "name":       "Body",
          "role":       "body",
          "family":     "Source Sans Pro",
          "weights":    [400, 600],
          "fontColor":  "#333333",
          "lineHeight": "1.6",
          "fallback":   "sans-serif",
          "sizes": { "recommended": 18 }
        }
      ]
    },

    /* ── Voice ───────────────────────────────── */
    "voice": {
      "tone":    ["confident", "clear", "human"],
      "tagline": "Your brand's tagline goes here"
    },

    /* ── Strategy ────────────────────────────── */
    "strategy": {
      "archetype":    "creator",
      "brandEssence": ["Honest", "Considered", "Purposeful"],
      "mission":      "We exist to...",
      "vision":       "A world where...",
      "brandPromise": "What we commit to delivering",
      "values": [
        {
          "name":        "Craft",
          "description": "We do things properly or not at all.",
          "behaviors":   ["Precision", "Care", "Quality"]
        }
      ],
      "targetAudience": {
        "primary":   "Describe your primary audience",
        "secondary": "Describe your secondary audience"
      }
    },

    /* ── Purpose ─────────────────────────────── */
    "purpose": {
      "statement":    "Why this brand exists beyond profit",
      "sdgAlignment": [8, 12],
      "metrics": [
        {
          "name":                 "Impact Metric",
          "unit":                 "units",
          "measurementFrequency": "monthly",
          "verificationStatus":   "unverified"
        }
      ]
    },

    /* ── Metadata ────────────────────────────── */
    "metadata": {
      "name":        "Example Brand",
      "version":     "1.0.0",
      "lastUpdated": "2026-01-01T00:00:00.000Z"
    }

  },

  "$schema":  "https://brandspec.org/schema/v0.1/brandspec.json",
  "version":  "0.1.0"
}

BrandSpec tokens are designed to compile to any downstream format. Below are reference patterns for the most common outputs.

CSS custom properties

Map colour and typography tokens directly to CSS variables at the :root level.

/* Generated from brandspec.json → brand.tokens */
:root {
  /* Colours */
  --color-primary: #1a1a2e;
  --color-accent:  #e94560;

  /* Typography */
  --font-heading:       'Plus Jakarta Sans', sans-serif;
  --font-heading-weight: 700;
  --font-heading-color:  #1a1a2e;
  --font-heading-size:   40px;
  --font-heading-lh:    1.2;

  --font-body:          'Source Sans Pro', sans-serif;
  --font-body-weight:    400;
  --font-body-color:     #333333;
  --font-body-size:      18px;
  --font-body-lh:       1.6;
}

JavaScript consumption

Read a BrandSpec file and extract tokens programmatically.

// Load and parse brandspec.json
const spec = await fetch('/brandspec.json').then(r => r.json());

const { tokens, voice, strategy } = spec.brand;

// Apply colour tokens to CSS variables
tokens.colors.forEach(color => {
  document.documentElement.style
    .setProperty(`--color-${color.name.toLowerCase()}`, color.hex);
});

// Get tone of voice descriptors
const tone = voice.tone.join(', ');
// → "confident, clear, human"

// Access brand positioning for an AI prompt
const brief = `
  Brand: ${spec.brand.metadata.name}
  Archetype: ${strategy.archetype}
  Tone: ${tone}
  Essence: ${strategy.brandEssence.join(', ')}
  Mission: ${strategy.mission}
`;

Figma Variables (API push)

BrandSpec colour tokens map directly to Figma Variable collections via the Figma REST API.

// Push BrandSpec colours to a Figma Variable collection
const variables = spec.brand.tokens.colors.map(color => ({
  name: `colour/${color.role}/${color.name}`,
  resolvedType: 'COLOR',
  valuesByMode: {
    default: {
      r: color.rgb.r / 255,
      g: color.rgb.g / 255,
      b: color.rgb.b / 255,
      a: 1
    }
  }
}));

// POST to Figma REST API → /v1/files/:key/variables

BrandSpec is designed to be standards-aware. Where relevant, it aligns with or extends existing open specifications rather than working against them.