Brand identity → design tokens: the handoff that decides whether it survives

Most brand identities do not fail in the design. They fail in the week after delivery, when an engineer opens a 60-page PDF, finds #FF0E9D under the heading “Primary”, types it into a component, and the second brand is born — the one that lives in the code and drifts a little further from the first one with every sprint.

The fix is mechanical and it is not expensive: hand the identity over as tokens rather than as pictures of decisions. This post is how we do that — what gets tokenised, how the names are structured, the rule that keeps the palette accessible, how themes are handled, and the checklist engineering can sign off against. The worked example is this site’s own token file, because publishing someone else’s would be guessing.

If you are earlier than the handoff — still deciding what the identity even includes — the SaaS brand kit lists the deliverables, and the brand guidelines template is the document that holds the decisions. This post is section ten of that template, at length.

What a design token actually is

A token is a named decision. --accent is a decision; #ff0e9d is a value that happens to be true today. The name is the contract between design and engineering: as long as both sides agree that “accent” means “the one thing you want clicked”, the hex behind it can change in one pull request and nothing else has to move.

That is the whole of the idea, and it is why “tokens” is not a synonym for “variables”. A variable is a place to put a value. A token is a place to put a meaning. A palette exported as --color-1 through --color-9 is variables — it tells an engineer nothing about which one a disabled button gets, so the decision moves into the component, where the brand cannot see it.

This is also where a token set differs from a design system: tokens are the values and their meanings, the system is the components built out of them. We wrote about that distinction in design system vs Figma file — the short version is that tokens are the part you can hand over in a week, and the part that keeps paying off even if the component library never gets built.

What to tokenise, and what to leave alone

Tokenise every value a second person would otherwise have to guess: colour, type family and scale, spacing, radius, border width, elevation, motion duration and easing, and the breakpoints. That list is short on purpose. It is also almost exactly the list of things that go wrong when two teams build two features in the same week.

Do not tokenise one-off decisions: the offset of an illustration in a hero, the width of a single marketing section, the rotation on a sticker. A token used once is a variable with ceremony, and a token file full of them stops being readable — which is the same as not having one.

The test we apply on handover: would a second person need this value, and would they be wrong if they guessed? Two yeses, it is a token.

The three tiers

Almost every token set that survives contact with a real product has three layers. Skipping the middle one is the most common mistake.

1. Primitives — the raw brand constants, named after what they are.

--pink:     #ff0e9d;
--pink-ink: #d0007b;
--cyan:     #16dcf2;
--black:    #0d0c11;

2. Semantic tokens — named after the job, pointing at a primitive. This is the layer components are allowed to use.

--accent:     var(--pink);      /* the one thing you want clicked */
--accent-ink: var(--pink-ink);  /* the same accent, safe at body size */
--base-bg:    #ffffff;
--base-fg:    #2b2b33;
--base-soft:  rgba(43, 43, 51, .70);

3. Component tokens — only where a component genuinely needs its own slot, such as a button’s disabled state that is not any of the semantic colours. Most teams need far fewer of these than they expect, and every one that is not truly needed is a place where the brand can drift.

The rule that makes the three tiers worth the trouble: components reference tier two, never tier one. The moment a card reads --pink directly, changing the accent stops being a one-line change, and the brand quietly develops exceptions nobody wrote down.

Name by role, not by hue or by number

Three naming schemes turn up in handovers, and two of them fail:

• --brand-pink fails the day the brand changes colour and every name lies.
• --color-3 fails immediately — nobody knows what it is for, so nobody uses it correctly.
• --accent, --surface, --ink, --ink-muted, --danger survives both, because the name describes the job.

The same applies to type and space. --text-body and --space-4 beat --font-16 and --gap-12, because when the body size moves to 17px, only the value changes — not every reference to it.

One more convention worth copying: keep the names stable across themes. --surface should mean “the page background” in light mode and in dark mode. If a theme needs a different name, it is not a theme — it is a second brand.

The contrast sibling — the rule brand colours usually break

Here is the failure we see most, and it is almost universal in identities designed on a white artboard: the brand colour is beautiful, and it is illegal as body text.

This site’s own pink is #ff0e9d. Against white it measures 3.62:1 — fine for display type, which needs 3:1, and below the 4.5:1 that body text needs. So the token set carries a sibling: --pink-ink: #d0007b, the same hue and saturation darkened until it clears 5.29:1. Small text uses the sibling; fills, borders and large display type keep the brand colour they were designed with.

The same treatment goes to the second accent: --cyan: #16dcf2 measures 1.67:1 on white and is display-only; --cyan-ink: #0995a4 clears the 3:1 large-text bar. And a third token settles the question of what goes on a brand-coloured fill: white on that pink is 3.62:1, near-black is 5.38:1, so --on-accent is near-black — which is also the sticker-button look the brand was built on. The accessible answer and the brand answer were the same answer; that is usually how it goes when the palette is decided at token level rather than per screen.

None of this is a compromise on the identity. The brand colour stays the brand colour everywhere it was designed to be. What the sibling buys is that nobody has to choose between the palette and a readable interface at 2am, because the choice is already in the file.

Theming without a second brand

Tokens earn their keep the moment the product has more than one surface treatment: light and dark, or — on this site — three bands that any section can sit on.

The mechanism is the same in both cases: the semantic names stay, the values are redefined per context.

.section.base   { background: var(--base-bg);   color: var(--base-fg); }
.section.contra { background: var(--contra-bg); color: var(--contra-fg); --accent-ink: var(--accent); }
.section.brand  { background: var(--brand-bg);  color: var(--brand-fg); }

Note the third declaration on the dark band. On a dark background the darkened ink is worse — it measures 3.51:1 there, while the undarkened pink clears 5.12:1 — so on that band --accent-ink points back at the plain accent. A component that writes color: var(--accent-ink) gets the right answer on every band without knowing which band it is on. That is the entire promise of semantic tokens, in one line of CSS.

Dark mode is the same job at product scale, and it is where “we’ll just invert it” collapses: inverted greys go muddy, brand colours vibrate on near-black, and shadows disappear. Every token gets a dark value, chosen and measured — it is an afternoon’s work when the token set exists, and a redesign when it does not.

The handoff itself

Figma variables are the source of truth. Not a page of swatches, not a PDF appendix — variables, in collections that mirror the tiers above, with modes for light and dark. Anything that is not a variable is a picture of a decision.

Export to a format engineering already reads. JSON (the W3C design-token shape if your tooling speaks it) or CSS custom properties directly. Which one matters far less than whether it is generated rather than transcribed: every value typed by hand is a place where the two copies start to differ.

Say who owns a change and how it is announced. A token change is a pull request and a line in a channel. Without that, the first “quick tweak” made straight in the codebase is the moment the Figma file becomes documentation of the past.

Hand over one page of prose with it. Not sixty: what the tiers are, which layer components may use, the contrast rule, and where to ask for an exception. That page is section ten of the brand guidelines template, and it is the part people actually read.

The five ways this goes wrong

1. The identity ships as a PDF. Engineering re-types the values; the copy in the code becomes the real brand within a month.
2. Components reference primitives. --pink in a card means the accent can never be changed in one place again.
3. The palette was only ever checked on white. Half of it fails at body size, and the fix arrives as per-screen exceptions instead of a sibling token.
4. Dark mode is described as “inverted”. It is not a theme; it is a promise that someone will improvise on a deadline.
5. Nobody owns the file. Six months later the tokens are a historical document, and the current brand is whatever the last contractor shipped.

The handoff checklist

Ten acceptance criteria. If the identity is being delivered by an outside studio, these are fair to put in the contract; if it is being built in-house, they are a definition of done.

1. Every colour, type, spacing, radius, elevation and motion value exists as a named token.
2. Names describe roles, not hues, and are stable across themes.
3. Three tiers exist, and components reference only the semantic tier.
4. Every accent has a contrast sibling for small text, with the measured ratio written down.
5. Light and dark values exist for every token, both measured — not derived by inversion.
6. Tokens are exported, not transcribed: Figma variables → JSON or CSS custom properties.
7. The product builds with zero hard-coded hex values, radii or durations in components.
8. One page of prose explains the tiers, the rule, and where to ask for an exception.
9. One named person owns changes, and the announcement path is written down.
10. A palette change can be made and shipped in a single pull request. If it cannot, one of the nine above is not true yet.

FAQ

What is the difference between design tokens and CSS variables? CSS custom properties are the delivery mechanism; tokens are the naming and the meaning behind them. A token set exported to CSS variables is tokens; a file of --color-1 … --color-9 is variables with no contract. The test is whether an engineer can pick the right one without asking a designer — that is the property a token has and a variable does not.

Should design tokens come from the brand identity or from the product? From the identity, then adjusted against the product. The identity decides the accent, the type and the personality; the product decides how many semantic slots are needed — disabled states, borders, focus rings, status colours — and reveals the values that fail in a dense interface. An identity that has never been checked against a real screen at body size usually needs a contrast sibling added.

How many tokens should a SaaS product have? Fewer than teams expect. A colour set of roughly a dozen semantic slots, a type scale of five or six steps, one spacing scale, two or three radii, two or three elevations and two motion durations covers most products. Growth should come from new modes — dark, high-contrast, density — not from new one-off names.

Can we add tokens to an existing product without a redesign? Yes, and it is the cheapest brand work available. Define the semantic layer over the values already in the code, replace hard-coded values file by file, and the first time the palette changes it will cost one pull request instead of a sprint. This is often what we do first in a brand identity engagement for a product that already ships.

Who owns design tokens after the handover? One named person, usually whoever maintains the design system or the front-end platform. Ownership means the change path exists: a pull request, a review, an announcement. Shared ownership in practice means no owner, and a token file with no owner is documentation of the past within two quarters.

---

If you want this done rather than described, tokens are a standard part of a brand identity engagement here — Figma variables plus the exported file, handed to engineering with the one page of prose, at published prices. And if you already have an identity and want to know whether it can survive the handoff, send a URL for a free 15-minute audit: the 16px logo test and the body-text contrast check take about four of those fifteen minutes.