Brand Guidelines vs Design Tokens

Open a brand guidelines PDF and a design-tokens file to “the same” blue, side by side. The PDF page shows a swatch, a paragraph about confidence and clarity, and a hex code typeset in a caption — a picture of the value. The tokens file shows "brand-600": { "$value": "#2563eb" } — the value itself, in a form Figma and a build pipeline read directly. One is documentation about the color; the other is the color, as far as software is concerned.

Brand guidelines and design tokens do different jobs, and most organizations need both: guidelines carry intent — why the brand looks the way it does, the voice, the dos and don’ts, the story a human needs to make a judgment call — while tokens carry values, the machine-readable answers that design and build tools consume without interpretation. The failure mode worth an article is using one for the other’s job. This one is part of our brand colors guide.

What job do brand guidelines actually do?

Guidelines — the brand book, in its classic form — exist to transfer judgment. They explain why the blue is blue, what it is meant to convey, where it belongs and where it must never appear, how the photography feels, how the brand speaks. Their reader is a human who is about to make a decision the rules did not anticipate: a new partnership deck, a trade-show wall, a format nobody has designed before. Intent is what generalizes to the unanticipated case — a value alone cannot tell you whether the new thing is on brand.

What job do design tokens do?

Tokens are the brand’s decisions as named values: brand-600 is this exact color, text-primary is this one, space-4 is this many pixels. Their consumers are mostly not people — Figma variables, stylesheets, component libraries and build steps read them directly, typically in a standard format such as DTCG JSON. A token answers exactly one kind of question — what is the value — and answers it identically for every consumer, every time. That sameness is the entire point: no interpretation, no approximation, no version of the blue that depends on who copied it.

What goes wrong when one does the other’s job?

A PDF as the value source decays by approximation. When the brand book is where values live, every reader extracts them by hand: an eyedropper on the swatch (often from a compressed export), a hex code retyped from memory, a screenshot matched by eye. Each copy drifts a little, each future surface copies from the nearest previous one, and within a few years the brand has five blues, none authoritative. The mechanism is human reading — a person re-expresses what they saw, and re-expression is where the error enters.

Tokens as the intent source explain nothing. A JSON file can tell a new designer that brand-600 is #2563eb; it cannot tell them why, or that the blue is reserved for actions, or that flooding a page with it is precisely what the brand should never do. When the unanticipated case arrives, a values-only system offers no help — and the designer improvises, plausibly and off-brand.

The intuitive version: humans keep the gist and machines keep the coordinates. An artifact aimed at humans gets read and re-told, and re-telling approximates; an artifact aimed at machines gets copied bit-for-bit. Route the story to the reader built for stories, and the numbers to the reader built for numbers.

What does the same decision look like written both ways?

One brand decision — blue is our action color — written as each artifact.

The guideline paragraph, carrying intent:

Blue is our action color. It appears wherever we ask something of the reader — buttons, links, the one highlighted number on a pricing page — and nowhere else. Against calm neutrals it reads as decisiveness; spread across a page it reads as noise. The exact values live in the token file under brand; interactive fills use accent with its paired text color on-accent.

The token entries, carrying values:

{
  "brand-600": { "$type": "color", "$value": "oklch(0.546 0.215 262.9)" },
  "accent":    { "$value": "{brand-600}" },
  "on-accent": { "$type": "color", "$value": "#ffffff" }
}

That oklch(0.546 0.215 262.9) is #2563eb, and white text on it measures ≈5.2:1 — which is why on-accent can be declared rather than improvised. Notice what each artifact carries that the other cannot. The paragraph holds “and nowhere else” — a rule about restraint that no token schema encodes. The entries hold the exact value and its verified pairing — a precision no paragraph survives being retyped from.

Open this guideline’s color decisions as a live token set in the Scale Composer — the blue as seed, the ramp derived from it, and the semantic roles with their contrast checks sitting next to the names the guideline refers to.

How should guidelines and tokens connect?

By reference, in one direction. The modern shape is guidelines that name tokens instead of embedding values: the PDF shows the color and says “this is brand-600”; the token file owns the number. The handoff line falls naturally — guidelines say our blue conveys decisiveness and is used for primary actions; tokens say brand-600 equals this exact value, and Figma and the codebase consume it directly.

The reason is the oldest rule in documentation: anything stated in two places will eventually disagree. If the PDF embeds #2563EB and the token file is later corrected or refined, the PDF is silently wrong — and it is the artifact people screenshot. If the PDF says “brand-600”, it stays true through every value change. Where possible, the swatch pages themselves are regenerated from the token file, so even the pictures are renderings of the source rather than rivals to it.

Where do you start?

From whichever artifact you already have. If guidelines exist but tokens don’t, harvest every literal value the PDF states — the hex codes, the type sizes, the spacing rules — into one token file, then edit the guidelines to name the tokens instead of embedding the numbers. Turn the values your guidelines state into a single token source — seed with the brand color, derive the ramp and the semantic roles, and export the DTCG, CSS or Figma Variables file your tools read directly.