Rolling Out a Rebrand via Tokens

A composite that many teams will recognize: the rebrand shipped over a weekend. Monday morning the site was live in the new teal and the launch thread was celebratory; by Friday the list had started — the old blue in the email templates, the checkout button nobody’s stylesheet controlled, the favicon, the PDF generator, the partner-portal header. The launch took two days. The mop-up took a quarter, one hardcoded hex value at a time.

With a tokenized product, a rebrand is a values release, not a rewrite: derive the new system from the new seed, diff the old token values against the new, re-verify every contrast pairing, stage the release behind flags or by surface — and budget separately for the long tail of whatever was never tokenized. The weekend team above did the first step and skipped the rest. This article — part of our brand colors guide — walks the sequence. It assumes the strategic work is already done: the pin list naming what carries recognition and must not move is written, and what follows is the mechanics of shipping everything that may.

Why is a rebrand a values release, not a rewrite?

Because in a tokenized product, components never contain colors — they reference roles, and roles resolve to values. The rebrand changes the answers, not the questions: accent still exists, still feeds the same buttons, and simply resolves to teal where it resolved to blue. Nothing structural moves, which is what makes the change reviewable, diffable and reversible — the same properties a code release has, because it is one.

How do you derive the new system?

From the new seed, not by editing values one at a time. In Scale Composer, load the project’s design-tokens.json, replace the seed with the rebrand color, and re-derive: the ramp, the tinted neutrals, the semantic roles and their on-colors rebuild from the new input, while the round-trip preserves what the rebrand doesn’t touch — the type scale, the spacing, the role structure itself. Re-deriving rather than hand-editing matters for a quiet reason: the old system’s values were related to each other (tints of one seed, text pairings verified against fills), and hand-edits break relationships one value at a time without anyone noticing until the palette audit.

Why is the token diff the rebrand’s real scope?

Because with old and new token files in hand, the diff between them is the technical scope of the rebrand — reviewable line by line, like code. Here is a mini diff, six tokens, old → new:

The danger-600 line is the one to sit with. Somewhere between concept and export, someone “harmonized” the error red while they were in the file — a change with real consequences (existing alerts shift, screenshots in the help docs go stale) that no one decided. In an untokenized rebrand this rides along invisibly; in a token diff it is one surprising line in a review. Surprising entries in the diff are scope creep made visible — which is the diff’s second job, after documenting the scope everyone agreed to.

Open the before and after palettes in Scale Composer — the old blue token values imported alongside the system derived from the new teal seed, with the changed values and their contrast checks readable in one view.

Why is contrast re-verification non-negotiable?

Because pairings that passed under the old values can fail under the new ones, silently. The concept deck’s teal — say #0d9488 — holds white text at only ≈3.7:1, where the old blue held it at ≈5.2:1. Same role, same white label, new fill: an accessibility regression shipped as an aesthetic choice. That is why the diff above shows brand-600 landing at #0f766e (≈5.5:1 with white) — deeper than the deck’s teal, because the re-derivation enforces the floors and pushes the shipping value until the pairing passes. The on-color re-derivation catches most of this class automatically; what it cannot catch are pairings that were created outside the system — which is step five’s problem.

How do you stage the release?

Like any release: gradually, with a way back. Because old and new are two value-sets behind the same roles, a tokenized product can run both simultaneously — which turns the big-bang rebrand into a controlled rollout. Put the new set behind a feature toggle and enable it per environment; or roll by surface (marketing site first, product second, transactional email last); or by market, if the rebrand’s messaging lands in waves. The teams that ship rebrands calmly are rarely braver — they have simply arranged for “oops” to be a flag flip rather than a re-release.

What doesn’t the token release cover?

Everything that never referenced a token — and the honest list is long: hardcoded hex in old templates (transactional email is the classic nest), raster assets with the old color baked in, favicons and app icons, generated PDFs, social templates in whoever-runs-Instagram’s account, third-party listings, and the printed material in the supply closet. Tokens don’t save you from what never consumed them; they save you from re-fighting the 90% that did, so the hunt can focus on this list. Budget the hunt as its own workstream — grep for the old values in every repository, inventory the assets, assign owners. The weekend team’s lost quarter was exactly this list, discovered instead of planned.

Where do you start?

With the two artifacts every later step consumes: the old token file and the new one derived from the rebrand seed. Re-derive your palette from the new seed and keep the old set alongside — load the project’s tokens, re-seed, and compare value by value: the changes are the rollout’s scope, its review, and its test plan in one.