Solutions · Design systems

Multi-brand design systems on one codebase

Several brands can share one frontend when their differences live in tokens and copy, not in forked components. We spec the token layers, check every brand theme for contrast and behaviour, and ship one codebase.

Updated 22 November 2026

The problem

Running several brands on one product usually starts with a copy. The second brand forks the first codebase, changes the colours, and ships. By the fourth brand there are four codebases, each with its own fixes, bugs and release calendar. A security patch ships four times. A new feature costs four times as much.

The other common failure is one codebase full of brand conditions. Components check which brand they are rendering and branch. Every new brand adds branches. Nobody can say what a component looks like without running it for every brand.

Accessibility suffers in both cases. A colour pair that passes contrast in one brand fails in another, and nobody notices until a user or an audit does.

What we put in the spec

We spec a design system where brands differ only in data: tokens, copy and assets. Components never know which brand they are rendering. The constitution states that rule, and the spec defines the layers that make it work.

Token layers

Layer Holds Example
Core Raw values: the full palette, type scale, spacing scale color.amber.600, space.4
Semantic Roles that components use color.action, color.surface, text.muted
Brand The mapping from semantic roles to core values for each brand Brand B: color.action → color.teal.700
Component (optional) Narrow overrides for one component button.radius

Components read only semantic and component tokens. Adding a brand means adding a brand mapping, not touching components.

Per-brand themes

Each brand can have light and dark themes, density settings and its own fonts. The spec lists every theme the product supports, so every theme can be tested.

Copy per brand

Brand names, tone, legal text and the copy that varies by market are kept in content files keyed by brand and market. Components receive copy. They don’t contain it.

Accessibility per theme

Every semantic colour pair is checked for every brand and theme. A brand mapping that fails WCAG 2.2 AA contrast is rejected, the same way a failing test is.

Feature: Brand themes meet contrast
  Scenario: A new brand mapping is added
    Given a brand mapping for every semantic colour role
    When the token build runs
    Then every text and background pair meets 4.5:1
    And every large-text and interface pair meets 3:1
    And the build fails and names any pair that does not

How it is checked before release

Brand bugs hide in combinations, so the checks run across all of them.

  • A token build with contrast checks: the token pipeline computes every semantic pair for every brand and theme, and fails on any pair below the threshold.
  • Visual regression per brand: key screens and components are captured for each brand and theme and compared on every pull request.
  • Component tests run against more than one brand: behaviour tests run with at least two brand mappings, so a component that secretly depends on one brand’s values is caught.
  • Copy completeness: a missing string for any brand and market pair fails the build rather than showing a fallback in production.

A senior engineer reviews every change, and the trace report records the results per brand.

What changes for you

A fix ships once and reaches every brand. A new brand becomes a configuration task with a clear checklist, not a new codebase. Design and engineering share one vocabulary, the semantic tokens, so design files and code stop drifting apart.

You can also answer an accessibility question for every brand at once, with evidence from the build.

What you receive

Deliverable Format
Token architecture and naming rules In the spec and plan
Core, semantic and brand token files In your repository, exportable to design tools
Theme list and brand mappings Versioned, one file per brand
Contrast checks in the token build Part of CI
Visual regression per brand and theme Part of CI
Guide to adding a brand A short document for your team

Decisions the spec records

A shared design system raises a few questions that teams often answer differently in each pull request. We answer them once, in the plan, so they stay answered.

  • Where a brand is allowed to differ: colour, type, radius, imagery and copy, but not layout logic or behaviour, unless the spec says so for a named component.
  • How a brand is selected: by domain, build, or runtime setting, and what happens if it is missing.
  • How tokens reach design tools: one source of truth in the repository, exported for design, never edited in two places.
  • Who approves a new brand mapping: a named role, after the contrast and visual checks pass.

Moving from forked codebases

If you already run several forks, we don’t rewrite them in one go. A Spec Sprint maps what each brand really changes. A Build then moves brands onto the shared system one at a time, behind a parity check, so each brand keeps working while it moves. A Retainer suits teams that add brands or markets on a regular cycle.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint