Multi-Brand Theming & Token System
Established a token architecture that lets multiple brands share one product foundation — with full visual differentiation and zero duplication across teams.
7
brands on one system
340+
tokens defined
60%
reduction in brand-switch time
0
duplicated component forks
Seven brands. One product codebase. Every team maintaining their own component forks — and diverging faster than they could be reconciled. Each brand release was a manual exercise in propagating changes through dozens of isolated files. The inconsistency was invisible at the component level and catastrophic at the product level.
The Fragmentation Problem
When each brand maintains its own component library, the first consequence is drift. Buttons look similar but aren't — border radius here, shadow there, hover state that nobody documented. Then one team fixes a bug in their fork and four other brands keep the bug. Then a new engineer joins and asks which library to use and gets five different answers.
The root cause isn't the brands — it's the absence of a shared source of truth. Design tokens are that source: a named layer of decisions that sits above any individual brand and makes the distinctions between brands explicit and manageable.
A token system's value isn't the tokens — it's the contract they create between design and engineering. When the same name resolves correctly in every context, teams stop duplicating decisions and start building on them.
Three-Layer Token Architecture
The system is structured in three layers. Global tokens define the raw palette — every colour, size, and spacing value the system will ever use. Semantic tokens map global values to purpose: `color.text.primary` or `color.surface.warning`. Brand tokens override semantic tokens at the theme level — so Brand A's primary becomes `#1a56db` and Brand B's becomes `#7c3aed`, but both resolve the same semantic names.
This layering means UI components reference only semantic tokens. Switching brand is switching which theme file loads — not which components are used.
Rolling Out Across Teams
Migration strategy mattered as much as the architecture. Teams couldn't drop existing components overnight. The rollout used a deprecation-first approach: parallel tokens with the old naming convention were marked deprecated, new semantic names introduced, and a six-week window gave teams time to migrate at their own pace.
The constraint that made this work was tooling: a token linter added to every PR pipeline flagged deprecated token usage before it merged. The migration became self-enforcing.
Linting tokens at the PR level was the decision that compressed the migration from estimated quarters to six weeks. Infrastructure that makes the right thing easy and the wrong thing visible is worth more than any amount of documentation.
Outcomes
After the migration, a full brand switch — previously a multi-day exercise involving manual file updates across teams — became a one-line theme import. New brand onboarding dropped from three weeks to under four days. Teams stopped maintaining forks and started contributing back to the shared system, because contributing back had lower friction than maintaining a divergent copy.
Token Layer Architecture
Global Tokens
blue-600 = #2563ebRaw values — the full palette and scale
Semantic Tokens
color.action.primary → blue-600Named by intent, not value
Brand Tokens
brand-a.action.primary → indigo-700Per-brand overrides of semantic layer
Component Tokens
button.bg → color.action.primaryComponent-scoped aliases (optional)
Semantic Colour Roles
Action
Primary
#ea580c
Secondary
#fed7aa
Hover
#c2410c
Surface
Default
#ffffff
Subtle
#f8fafc
Elevated
#f1f5f9
Feedback
Success
#10b981
Warning
#f59e0b
Error
#ef4444
System Components
ThemeProvider
Wraps the app and resolves the active brand token set. Supports runtime switching with no re-renders.
TokenAudit CLI
Scans a codebase for deprecated token usage and generates a migration report with suggested replacements.
BrandConfig Schema
JSON schema defining what a valid brand override file must contain. Prevents misconfigured themes from shipping.
DesignToken Linter
ESLint plugin that flags hardcoded colour and spacing values, enforcing token usage at the PR level.
Key Takeaways
Three-layer token architecture (global → semantic → brand) makes brand switching a theme swap, not a migration
Tooling that enforces the right pattern at PR time compresses adoption timelines from months to weeks
Deprecation-first rollouts allow gradual migration without blocking existing teams
The system's value is the contract it creates, not the tokens themselves