Complete Multi-Brand Design System Architecture: Build…

Picture this: You've built a bulletproof component library. Your button component works flawlessly across desktop, tablet, and mobile. The color system is airtight. Your team ships features three times faster than they did before.

Then the email arrives. "We just acquired a new brand." Or worse: "We're launching a white-label platform for SaaS agencies, and each tenant needs their own theme."

So what do you do? Rebuild the button? Hardcode a dozen hex values? Create brand-specific component forks that diverge further with every release?

By the end of this article, you won't have to. A multi-brand design system doesn't ask you to rebuild anything. Instead, it lets you build once and theme infinitely—leveraging design token layering, CSS custom properties, Figma variable modes, and intelligent component architecture to power unlimited visual identities from a single codebase. This is the pattern that separates mature design systems from ones that collapse under their own weight at scale.

figma

learn about Angular Development

design systems

angular development

Figma Dev Mode 2025: The Complete Angular Developer Guide to Design Handoff

The Multi-Brand Challenge

Building a component library is hard. Building a component library that serves multiple brands is an order of magnitude harder—unless you design for it from the start.

Most teams encounter this problem reactively. A product launches with a cohesive visual identity. Then a merger happens. A new market demands a regional rebrand. A SaaS platform pivots to white-label. Suddenly, the design system that was built around a single brand buckles under the weight of supporting three, five, or ten variations of the same components.

The failure modes are predictable:

Hardcoded values scattered across components. When hex colors live in component files instead of token files, changing a brand means find-and-replace across hundreds of component definitions. Risky. Slow. A disaster waiting to happen when you inevitably miss one.

Brand-specific component forks. You create BrandA-Button, BrandB-Button, BrandC-Button. Maintenance becomes exponential. A bug fix in BrandA-Button doesn't automatically apply to the others. Over time, the forks diverge completely, and the codebase becomes unmaintainable.

Hardcoded theme imports. If your application imports a single theme.scss file and builds a static CSS output for one brand, scaling to ten brands means ten separate builds, ten separate deployments, and ten separate code paths to maintain.

Disconnected design-to-dev workflows. Designers work in Figma with Brand A colors. Developers implement in code with slightly different hex values. When Brand B launches, the design system and the codebase tell different stories.

No runtime switching. If your theme is baked into the compiled CSS, supporting dynamic brand switching (say, in a white-label SaaS where tenants have their own themes) becomes a hacky afterthought bolted onto the application layer rather than a first-class architecture concern.

The antidote to all of these is token layering—a deliberate architectural pattern where you separate what you're coloring from how you're coloring it.

Token Layering: The Architecture That Makes It Possible

The magic of multi-brand design systems lives in token layering. Instead of a flat list of design tokens, you organize tokens into three distinct layers, each serving a specific purpose. Each layer knows how to consume the layer below and expose values to the layer above.

Layer 1: Global Tokens define primitive values with zero semantic meaning. They're named for what they are, not what they do. Color-Slate-600. Space-08. FontSize-14. These tokens are identical across all brands because they describe the raw material—the palette and spacing scale—that any brand might use.

Layer 2: Alias Tokens (or semantic tokens) give global tokens meaning in context. They map primitives to specific roles in the design system. ColorPrimary (which might reference Color-Blue-500 in Brand A but Color-Indigo-600 in Brand B). ColorBackground. SpacingBase. FontWeightHeading. Aliases are where brands differ—each brand has its own alias token file that points to different global tokens.

Layer 3: Component Tokens are the final consumers. Components never reference global tokens or alias tokens directly. Instead, they reference component tokens: ButtonPrimaryBg, ButtonPrimaryText, ButtonPrimaryHover. These live in a shared component token file that references alias tokens, ensuring that when an alias token changes (at brand-switch time), the component automatically updates.

Here's the layered structure in table form:

Layer	Naming Convention	Example Token Name	Example Value	Changes Per Brand?
Global	`[Category]-[Hue]-[Shade]`	`Color-Blue-500`	`#3b82f6`	No — same across all brands
Alias	`[Semantic Role]`	`ColorPrimary`	`$Color-Blue-500` (Brand A) / `$Color-Indigo-600` (Brand B)	Yes — each brand maps differently
Component	`[Component][Property][State]`	`ButtonPrimaryBg`	`$ColorPrimary`	No — points to alias, stays constant

When you want to launch Brand B, you don't touch the global layer (it's universal) or the component layer (it's generic). You only change the alias layer. ColorPrimary now points to a different global token. Instantly, every button, badge, link, and input that consumes ColorPrimary through the component token layer updates to the new brand's primary color.

The CSS custom property file structure looks like this:

/* Global tokens — identical across all brands */
:root {
  --color-slate-50: #f8fafc;
  --color-slate-100: #f1f5f9;
  --color-slate-200: #e2e8f0;
  --color-blue-400: #60a5fa;
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-indigo-600: #4f46e5;
  --color-gray-900: #111827;
  
  --space-4: 0.25rem;
  --space-8: 0.5rem;
  --space-12: 0.75rem;
  --space-16: 1rem;
}

/* Alias tokens — Brand A defaults (loaded by default) */
:root {
  --color-primary: var(--color-blue-500);
  --color-primary-dark: var(--color-blue-600);
  --color-background-primary: var(--color-slate-50);
  --color-text-primary: var(--color-gray-900);
  
  --space-base: var(--space-8);
  --space-lg: var(--space-16);
}

/* Alias token overrides for Brand B */
[data-brand="brand-b"] {
  --color-primary: var(--color-indigo-600);
  --color-primary-dark: var(--color-indigo-700);
  --color-background-primary: var(--color-slate-100);
}

/* Component tokens — universal, consume alias layer */
:root {
  --button-primary-bg: var(--color-primary);
  --button-primary-bg-hover: var(--color-primary-dark);
  --button-primary-text: white;
  
  --input-bg: var(--color-background-primary);
  --input-text: var(--color-text-primary);
  --input-border: var(--color-slate-200);
}

This structure is the foundation. Every pattern that follows—Figma variable modes, Angular theme services, Style Dictionary pipelines—all build on top of this three-layer token model.

Figma Variable Modes for Multi-Brand

The design system is only as strong as the design-to-dev handoff. If designers are working with one color system in Figma and developers are implementing another, you've already lost.

Figma variable modes solve this by letting you define multiple sets of token values within a single variable collection. Instead of creating separate Figma files for Brand A and Brand B, you create one file with two modes.

Here's how it works in practice:

Create a variable collection — say, "Design Tokens."
Define variables — Color/Primary, Color/Background, Space/Base, etc.
Create modes — "Brand A" and "Brand B."
Assign values per mode — In "Brand A" mode, Color/Primary = blue. In "Brand B" mode, Color/Primary = indigo.
Bind variables to components once. Now when a designer switches modes, all components using that variable instantly update to reflect the new brand.

The result: designers can sit in a single Figma file, switch between brand modes with a dropdown, and validate that the component library works across all brands without duplication or drift.

This single-file-multiple-modes approach is transformative because it:

Eliminates file sprawl. One file to maintain, not three.
Keeps design and code in sync. The token values in Figma modes match the token values in your CSS custom property files.
Makes brand validation instant. A designer can preview a component library under five different brands in minutes, catching inconsistencies before they reach code.
Simplifies component maintenance. When you update a component, the update automatically applies to all brand modes.

For a deeper technical dive on how to structure variables for maximum flexibility, see the related guide on design tokens with Figma variables and Style Dictionary.

CSS Custom Properties Implementation

CSS custom properties (CSS variables) are the runtime glue that makes multi-brand theming possible without rebuilding your application.

Unlike Sass variables, which are compiled away at build time, CSS custom properties are calculated at runtime. This means you can change them dynamically—even in the browser console—and see the change reflected instantly across all components that reference them.

Here's a complete example showing how three brands coexist in the same CSS file:

/* ====== GLOBAL TOKENS ====== */
:root {
  /* Color Palette */
  --color-slate-50: #f8fafc;
  --color-slate-100: #f1f5f9;
  --color-slate-200: #e2e8f0;
  --color-slate-600: #475569;
  --color-slate-900: #0f172a;
  
  --color-blue-400: #60a5fa;
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-blue-700: #1d4ed8;
  
  --color-indigo-600: #4f46e5;
  --color-indigo-700: #4338ca;
  
  --color-emerald-500: #10b981;
  --color-emerald-600: #059669;
  
  /* Spacing Scale */
  --space-0: 0;
  --space-4: 0.25rem;
  --space-8: 0.5rem;
  --space-12: 0.75rem;
  --space-16: 1rem;
  --space-20: 1.25rem;
  --space-24: 1.5rem;
  --space-32: 2rem;
  
  /* Typography */
  --font-size-12: 0.75rem;
  --font-size-14: 0.875rem;
  --font-size-16: 1rem;
  --font-size-18: 1.125rem;
  --font-size-20: 1.25rem;
  
  --font-weight-regular: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
}

/* ====== ALIAS TOKENS (Brand A - Default) ====== */
:root {
  /* Primary Color System */
  --color-primary: var(--color-blue-500);
  --color-primary-light: var(--color-blue-400);
  --color-primary-dark: var(--color-blue-700);
  --color-primary-contrast: white;
  
  /* Background & Surface */
  --color-background: var(--color-slate-50);
  --color-surface: white;
  --color-surface-alt: var(--color-slate-100);
  
  /* Text Colors */
  --color-text-primary: var(--color-slate-900);
  --color-text-secondary: var(--color-slate-600);
  --color-text-inverse: white;
  
  /* Semantic Colors */
  --color-success: var(--color-emerald-500);
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: var(--color-blue-500);
  
  /* Borders */
  --color-border: var(--color-slate-200);
  
  /* Spacing System */
  --space-base: var(--space-8);
  --space-sm: var(--space-4);
  --space-md: var(--space-12);
  --space-lg: var(--space-16);
  --space-xl: var(--space-24);
}

/* ====== ALIAS TOKENS (Brand B Override) ====== */
[data-brand="brand-b"] {
  --color-primary: var(--color-indigo-600);
  --color-primary-light: var(--color-indigo-500);
  --color-primary-dark: var(--color-indigo-700);
  
  --color-success: var(--color-emerald-600);
}

/* ====== ALIAS TOKENS (Brand C Override) ====== */
[data-brand="brand-c"] {
  --color-primary: var(--color-emerald-500);
  --color-primary-light: var(--color-emerald-400);
  --color-primary-dark: var(--color-emerald-600);
  
  --color-background: white;
  --color-surface: var(--color-slate-50);
}

/* ====== COMPONENT TOKENS ====== */
/* Button Component */
.btn-primary {
  background-color: var(--color-primary);
  color: var(--color-primary-contrast);
  padding: var(--space-md) var(--space-lg);
  border: 2px solid transparent;
  border-radius: 0.375rem;
  font-size: var(--font-size-16);
  font-weight: var(--font-weight-semibold);
  cursor: pointer;
  transition: all 0.2s ease;
}

.btn-primary:hover {
  background-color: var(--color-primary-dark);
  transform: translateY(-2px);
}

.btn-primary:active {
  transform: translateY(0);
}

/* Input Component */
.input-base {
  width: 100%;
  padding: var(--space-md) var(--space-lg);
  border: 1px solid var(--color-border);
  border-radius: 0.375rem;
  font-size: var(--font-size-16);
  background-color: var(--color-surface);
  color: var(--color-text-primary);
  transition: border-color 0.2s ease;
}

.input-base:focus {
  outline: none;
  border-color: var(--color-primary);
  box-shadow: 0 0 0 3px rgba(var(--color-primary), 0.1);
}

/* Card Component */
.card {
  background-color: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 0.5rem;
  padding: var(--space-xl);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

The power of this approach becomes obvious when you want to switch brands. To activate Brand B at runtime, you simply set the data-brand attribute:

document.documentElement.setAttribute('data-brand', 'brand-b');

Every CSS custom property that has been overridden for [data-brand="brand-b"] updates instantly. All components that reference those tokens update instantly. No rebuild. No page reload. Just a synchronous DOM update.

Angular Theme Service Architecture

In a real-world Angular application, you need a service to manage brand switching, load brand-specific token files, and persist the user's brand preference to localStorage.

Here's a production-ready BrandService built with Angular signals:

import { Injectable, signal } from '@angular/core';
import { HttpClient } from '@angular/common/http';

export interface BrandConfig {
  id: string;
  name: string;
  tokenFile: string;
  primary: string;
  secondary?: string;
}

@Injectable({
  providedIn: 'root'
})
export class BrandService {
  private readonly STORAGE_KEY = 'app-brand';
  private readonly DEFAULT_BRAND = 'brand-a';
  
  private readonly brandRegistry = new Map<string, BrandConfig>([
    [
      'brand-a',
      {
        id: 'brand-a',
        name: 'Brand A',
        tokenFile: '/assets/tokens/brand-a-aliases.css',
        primary: '#3b82f6'
      }
    ],
    [
      'brand-b',
      {
        id: 'brand-b',
        name: 'Brand B',
        tokenFile: '/assets/tokens/brand-b-aliases.css',
        primary: '#4f46e5'
      }
    ],
    [
      'brand-c',
      {
        id: 'brand-c',
        name: 'Brand C',
        tokenFile: '/assets/tokens/brand-c-aliases.css',
        primary: '#10b981'
      }
    ]
  ]);

  /* Signal-based reactive state */
  activeBrand = signal<string>(this.getInitialBrand());
  activeBrandConfig = signal<BrandConfig | null>(null);
  isLoadingBrand = signal(false);
  brandError = signal<string | null>(null);

  constructor(private http: HttpClient) {
    this.loadBrand(this.activeBrand());
  }

  /**
   * Determine initial brand from localStorage or use default
   */
  private getInitialBrand(): string {
    if (typeof localStorage !== 'undefined') {
      const stored = localStorage.getItem(this.STORAGE_KEY);
      if (stored && this.brandRegistry.has(stored)) {
        return stored;
      }
    }
    return this.DEFAULT_BRAND;
  }

  /**
   * Switch to a different brand
   * 1. Validate brand exists
   * 2. Load token file
   * 3. Apply data-brand attribute
   * 4. Persist to localStorage
   */
  async switchBrand(brandId: string): Promise<void> {
    if (!this.brandRegistry.has(brandId)) {
      this.brandError.set(`Brand "${brandId}" not found`);
      return;
    }

    this.isLoadingBrand.set(true);
    this.brandError.set(null);

    try {
      await this.loadBrand(brandId);
      this.activeBrand.set(brandId);
      
      if (typeof localStorage !== 'undefined') {
        localStorage.setItem(this.STORAGE_KEY, brandId);
      }
    } catch (error) {
      this.brandError.set(`Failed to load brand: ${error}`);
    } finally {
      this.isLoadingBrand.set(false);
    }
  }

  /**
   * Load brand tokens and apply to DOM
   * - Fetch token file
   * - Inject <link> tag
   * - Set data-brand attribute
   */
  private async loadBrand(brandId: string): Promise<void> {
    const config = this.brandRegistry.get(brandId);
    if (!config) return;

    // Load the brand-specific CSS token file
    await this.loadTokenFile(config.tokenFile);

    // Apply data-brand attribute to root
    document.documentElement.setAttribute('data-brand', brandId);

    // Update signal
    this.activeBrandConfig.set(config);
  }

  /**
   * Load external CSS token file dynamically
   */
  private loadTokenFile(href: string): Promise<void> {
    return new Promise((resolve, reject) => {
      // Remove existing brand token link if present
      const existing = document.getElementById('brand-tokens');
      if (existing) {
        existing.remove();
      }

      // Create and inject new link
      const link = document.createElement('link');
      link.id = 'brand-tokens';
      link.rel = 'stylesheet';
      link.href = href;

      link.onload = () => resolve();
      link.onerror = () => reject(new Error(`Failed to load ${href}`));

      document.head.appendChild(link);
    });
  }

  /**
   * Get all available brands
   */
  getAvailableBrands(): BrandConfig[] {
    return Array.from(this.brandRegistry.values());
  }

  /**
   * Get current brand config
   */
  getCurrentBrandConfig(): BrandConfig | null {
    return this.activeBrandConfig();
  }

  /**
   * Reset to default brand
   */
  resetToDefault(): void {
    this.switchBrand(this.DEFAULT_BRAND);
  }
}

To initialize this service and load the brand on app startup, use APP_INITIALIZER:

import { APP_INITIALIZER, ApplicationConfig } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: (brandService: BrandService) => {
        return () => {
          // Brand is already loaded in BrandService constructor
          // This ensures the brand is ready before first component renders
          return Promise.resolve();
        };
      },
      deps: [BrandService],
      multi: true
    }
  ]
};

And in a component, switch brands like this:

import { Component } from '@angular/core';
import { BrandService } from './services/brand.service';

@Component({
  selector: 'app-brand-switcher',
  template: `
    <div class="brand-switcher">
      <label>Select Brand:</label>
      <select (change)="onBrandChange($event)">
        <option 
          *ngFor="let brand of brandService.getAvailableBrands()"
          [value]="brand.id">
          {{ brand.name }}
        </option>
      </select>
      <p *ngIf="brandService.brandError()">
        Error: {{ brandService.brandError() }}
      </p>
    </div>
  `
})
export class BrandSwitcherComponent {
  constructor(public brandService: BrandService) {}

  onBrandChange(event: Event): void {
    const brandId = (event.target as HTMLSelectElement).value;
    this.brandService.switchBrand(brandId);
  }
}

The signal-based approach ensures that any component watching activeBrand() or activeBrandConfig() automatically updates when the brand changes, triggering reactive updates throughout the application.

Style Dictionary for Multi-Brand Token Pipeline

For teams with multiple platforms—web (CSS/SCSS), iOS (Swift), Android (Kotlin), and more—Style Dictionary transforms a single source of truth into platform-specific token outputs.

Style Dictionary takes your token definitions (usually in JSON or YAML format) and runs them through a build pipeline that generates CSS, SCSS, JSON, Swift, Kotlin, and more—one output per platform, optionally per brand.

A typical multi-brand Style Dictionary config looks like this:

{
  "source": [
    "tokens/global/**/*.json",
    "tokens/brands/{brandA,brandB,brandC}/**/*.json"
  ],
  "platforms": {
    "web-css": {
      "transformGroup": "web",
      "buildPath": "dist/tokens/",
      "files": [
        {
          "destination": "tokens-global.css",
          "format": "css/variables",
          "filter": { "attributes": { "type": "global" } }
        },
        {
          "destination": "brand-a-aliases.css",
          "format": "css/variables",
          "options": { "selector": ":root" },
          "filter": {
            "attributes": { "brand": "brand-a" }
          }
        },
        {
          "destination": "brand-b-aliases.css",
          "format": "css/variables",
          "options": { "selector": "[data-brand='brand-b']" },
          "filter": {
            "attributes": { "brand": "brand-b" }
          }
        }
      ]
    },
    "web-scss": {
      "transformGroup": "web",
      "buildPath": "src/styles/",
      "files": [
        {
          "destination": "_tokens.scss",
          "format": "scss/variables",
          "filter": { "attributes": { "type": "global" } }
        }
      ]
    },
    "ios-swift": {
      "transformGroup": "ios",
      "buildPath": "ios/generated/",
      "files": [
        {
          "destination": "ColorTokens.swift",
          "format": "ios/colors",
          "filter": { "attributes": { "type": "color" } }
        },
        {
          "destination": "TypographyTokens.swift",
          "format": "ios/typography",
          "filter": { "attributes": { "type": "typography" } }
        }
      ]
    },
    "android-kotlin": {
      "transformGroup": "android",
      "buildPath": "android/app/src/main/java/generated/",
      "files": [
        {
          "destination": "ColorTokens.kt",
          "format": "android/colors",
          "filter": { "attributes": { "type": "color" } }
        }
      ]
    }
  }
}

Your token source files are organized like this:

tokens/
├── global/
│   ├── colors.json
│   ├── spacing.json
│   └── typography.json
└── brands/
    ├── brand-a/
    │   ├── aliases.json
    │   └── components.json
    ├── brand-b/
    │   └── aliases.json
    └── brand-c/
        └── aliases.json

Each aliases.json file in a brand folder contains alias token overrides for that brand:

{
  "color": {
    "primary": {
      "value": "{color.blue.500}",
      "type": "color",
      "attributes": { "brand": "brand-b" }
    },
    "primary-dark": {
      "value": "{color.blue.700}",
      "type": "color",
      "attributes": { "brand": "brand-b" }
    }
  }
}

When you run style-dictionary build, it generates separate CSS files for each brand:

style-dictionary build
# Outputs:
# dist/tokens/tokens-global.css
# dist/tokens/brand-a-aliases.css
# dist/tokens/brand-b-aliases.css
# dist/tokens/brand-c-aliases.css
# src/styles/_tokens.scss
# ios/generated/ColorTokens.swift
# android/app/src/main/java/generated/ColorTokens.kt

This approach scales beautifully. When Brand D launches, you add one new brand folder with one new aliases.json file, re-run the build, and your entire platform ecosystem (web, iOS, Android) automatically gets Brand D token outputs.

Component Architecture for Themability

The final piece is designing your components to be theme-agnostic from the ground up.

This means:

No hardcoded colors or spacing. Every visual property comes from a token.
Components consume component tokens, not alias tokens. This ensures a clear separation between brand tokens and component implementation.
Structural vs. visual separation. The component defines the structure (HTML, layout, interaction); tokens define the visual presentation (colors, sizes, typography).

Here's an Angular button component that embodies these principles:

import { Component, Input } from '@angular/core';

/**
 * Primary Button Component
 * 
 * Purely structural. All visual properties are driven by CSS custom properties
 * defined in the component token layer. Supports any brand without code changes.
 */
@Component({
  selector: 'app-button-primary',
  template: `
    <button 
      [class.is-loading]="isLoading"
      [disabled]="isDisabled || isLoading"
      (click)="onClick()">
      <span *ngIf="!isLoading" class="btn-text">
        <ng-content></ng-content>
      </span>
      <span *ngIf="isLoading" class="btn-spinner">
        <i class="spinner"></i>
      </span>
    </button>
  `,
  styles: [`
    :host {
      display: inline-block;
    }

    button {
      /* Component token consumption */
      background-color: var(--button-primary-bg);
      color: var(--button-primary-text);
      border: 2px solid transparent;
      padding: var(--button-primary-padding, var(--space-md) var(--space-lg));
      border-radius: var(--button-primary-radius, 0.375rem);
      font-size: var(--button-primary-font-size, var(--font-size-16));
      font-weight: var(--button-primary-font-weight, var(--font-weight-semibold));
      cursor: pointer;
      transition: all 0.2s ease;
      min-width: var(--button-primary-min-width, 80px);
      position: relative;
    }

    button:hover:not(:disabled) {
      background-color: var(--button-primary-bg-hover);
      transform: translateY(-2px);
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
    }

    button:active:not(:disabled) {
      transform: translateY(0);
      box-shadow: 0 2px 6px rgba(0, 0, 0, 0.1);
    }

    button:disabled {
      opacity: 0.5;
      cursor: not-allowed;
    }

    button:focus {
      outline: 2px solid var(--button-primary-focus-ring, var(--color-primary));
      outline-offset: 2px;
    }

    .btn-text {
      display: inline-block;
      transition: opacity 0.2s ease;
    }

    .is-loading .btn-text {
      opacity: 0;
      position: absolute;
    }

    .btn-spinner {
      display: inline-block;
    }

    .spinner {
      display: inline-block;
      width: 16px;
      height: 16px;
      border: 2px solid rgba(255, 255, 255, 0.3);
      border-top: 2px solid white;
      border-radius: 50%;
      animation: spin 0.8s linear infinite;
    }

    @keyframes spin {
      to { transform: rotate(360deg); }
    }
  `]
})
export class ButtonPrimaryComponent {
  @Input() isDisabled = false;
  @Input() isLoading = false;

  onClick(): void {
    // Emit event or trigger action
  }
}

Notice what's absent: hardcoded #3b82f6 or #4f46e5. No hex values tied to specific brands. The component references only CSS custom properties—and those properties point to the component token layer, which points to the alias layer, which points to the global layer.

When you switch brands, the CSS custom property --button-primary-bg automatically updates (because it's set via the alias layer), and the button updates with it. The component code never changes.

Storybook for Multi-Brand Visual Testing

Storybook is where you validate that your multi-brand design system actually works across all brands. With the right setup, you can switch brands inside Storybook and visually regression-test every component under every brand.

Create a brand switcher toolbar addon:

// Brand Switcher Addon for Storybook
import { ADDON_ID, PANEL_ID } from './constants';
import { addons, types } from '@storybook/manager-api';

addons.register(ADDON_ID, (api) => {
  addons.add(PANEL_ID, {
    type: types.TOOL,
    title: 'Brand Switcher',
    match: ({ viewMode }) => viewMode === 'story',
    render: () => {
      const [brand, setBrand] = useState('brand-a');

      return (
        <div style={{ padding: '10px' }}>
          <select value={brand} onChange={(e) => setBrand(e.target.value)}>
            <option value="brand-a">Brand A (Blue)</option>
            <option value="brand-b">Brand B (Indigo)</option>
            <option value="brand-c">Brand C (Emerald)</option>
          </select>
        </div>
      );
    }
  });
});

Then run per-brand snapshot tests:

npm run test:visual -- --update-snapshots --brands brand-a,brand-b,brand-c

This ensures that if a token changes, you catch visual regressions across all brands before they reach production.

For a comprehensive guide on setting up Storybook with Angular design systems, see Storybook Angular Design System Documentation Guide 2025.

Governance: Shared vs Brand-Specific Components

At scale, you'll need a decision framework for when to create brand-specific components vs. extend existing ones through tokens.

Use token theming (alias layer) when:

Only colors, spacing, or typography differ
The component structure is identical across brands
Examples: buttons, inputs, cards, badges

Create component extensions when:

The component structure differs (e.g., Brand B requires an icon slot that Brand A doesn't)
Behavior changes by brand (e.g., Brand C modals have a different animation)
Rarely: when a component is so visually distinct that it's easier to rebuild than extend

Decision Matrix:

Requirement	Solution	Example
Different primary color	Alias token swap	`--color-primary` → Brand A: blue, Brand B: indigo
Different spacing	Alias token swap	`--space-lg` → Brand A: 1rem, Brand B: 1.25rem
Different typography	Alias token swap	`--font-weight-heading` → Brand A: bold, Brand B: semibold
Different component icon	Component token override	`--button-icon-size` → Brand A: 16px, Brand B: 20px
Different button shape	Brand-specific component	`ButtonPrimary` vs `ButtonPrimaryRounded` (Brand C only)
Different interaction pattern	Brand-specific component	`ModalDialog` vs `ModalSidebar` (Brand B only)

When you do create brand-specific components, namespace them clearly:

// Shared across all brands
export { ButtonPrimary } from './button-primary.component';

// Brand-specific (Brand C only)
export { ButtonPrimaryRounded } from './brand-c/button-primary-rounded.component';

Document the decision in your component library's contribution guidelines so teams know when to extend vs. fork.

Performance: Lazy-Loading Brand Tokens

On applications serving multiple brands, users typically only load one brand at startup. Loading all brand token files wastes bandwidth and parsing time.

Lazy-load non-critical brand tokens:

/**
 * Load brand tokens only when the user switches to that brand
 * 
 * Critical tokens (Brand A) are loaded in the <link> tag on the HTML page
 * Other brands are loaded on-demand via the BrandService
 */
private async loadTokenFile(href: string): Promise<void> {
  return new Promise((resolve, reject) => {
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = href;
    link.onload = () => resolve();
    link.onerror = () => reject(new Error(`Failed to load ${href}`));
    document.head.appendChild(link);
  });
}

For the critical path (Brand A on initial load), include the token file directly in your HTML template:

<!DOCTYPE html>
<html>
<head>
  <!-- Critical brand tokens (Brand A) loaded synchronously -->
  <link rel="stylesheet" href="/assets/tokens/tokens-global.css">
  <link rel="stylesheet" href="/assets/tokens/brand-a-aliases.css">
</head>
<body>
  <app-root></app-root>
</body>
</html>

This ensures no flash of unstyled content (FOUC) on the initial load while still lazy-loading other brands only when needed.

Case Study Pattern: B2B SaaS White-Label

A practical pattern that ties all of this together: white-label SaaS where each tenant has their own brand configuration.

When a user logs in, the API returns their tenant's brand ID and token overrides:

{
  "user": {
    "id": "user-123",
    "tenantId": "tenant-acme",
    "email": "alice@acme.com"
  },
  "tenant": {
    "id": "tenant-acme",
    "name": "ACME Corp",
    "brand": "brand-acme",
    "tokens": {
      "color-primary": "#d97706",
      "color-secondary": "#92400e",
      "font-family-heading": "'Playfair Display', serif"
    }
  }
}

Load the tenant's brand during app initialization:

export const APP_INITIALIZER: Provider = {
  provide: APP_INITIALIZER,
  useFactory: (authService: AuthService, brandService: BrandService) => {
    return async () => {
      const user = await authService.getCurrentUser();
      if (user && user.tenant) {
        // Register tenant-specific brand
        brandService.registerBrand(user.tenant.brand, {
          id: user.tenant.brand,
          name: user.tenant.name,
          tokenFile: `/api/tenants/${user.tenant.id}/tokens.css`
        });

        // Switch to tenant's brand
        await brandService.switchBrand(user.tenant.brand);
      }
    };
  },
  deps: [AuthService, BrandService],
  multi: true
};

The API serves the tenant's token file dynamically:

// Server endpoint
@Get('/api/tenants/:tenantId/tokens.css')
getTenantTokens(@Param('tenantId') tenantId: string) {
  const tenant = this.tenantsService.getTenant(tenantId);
  const cssVariables = this.tokenService.generateCSSVariables(tenant.tokens);
  return new StreamableFile(Buffer.from(cssVariables), {
    type: 'text/css'
  });
}

The generated CSS might look like:

[data-brand="brand-acme"] {
  --color-primary: #d97706;
  --color-primary-light: #f59e0b;
  --color-primary-dark: #b45309;
  
  --color-secondary: #92400e;
  
  --font-family-heading: 'Playfair Display', serif;
}

Each tenant sees their own branding, running the exact same codebase, with zero hardcoded tenant-specific logic in the application. The design system scales to thousands of tenants without modification.

Closing: One System, Infinite Brands

Multi-brand design systems are not a single tool or technique. They're an architectural philosophy baked into every layer—design tokens, CSS, component design, Figma workflow, and application services.

When you get this right, something profound shifts. You stop thinking in terms of "redesigning for a new brand" and start thinking in terms of "registering new token values." A rebrand that used to take weeks of development becomes a JSON file swap. A new white-label client becomes a configuration change, not a codebase fork.

This is scalability at the design system level—the kind that compounds. Each new brand doesn't multiply complexity; complexity stays flat because the architecture was designed for infinite variation from the start.

The patterns in this guide—token layering, CSS custom properties, Figma variable modes, Style Dictionary pipelines, and Angular service architecture—are production-tested across enterprise systems serving dozens of brands. Implement them together, and you'll find yourself with a design system that doesn't just support multiple brands. It's actually made better by supporting them.

Build once. Theme infinitely. That's the promise of a true multi-brand design system.

FAQ

Q: What is a multi-brand design system?

A: A multi-brand design system is a component library architecture where a single set of components can render under different visual themes (brands) by swapping design token values, without any code changes to the components themselves. This approach dramatically reduces development time and maintenance overhead when serving multiple brands or white-label clients.

Q: How do design tokens enable multi-brand theming?

A: Design tokens use a layered architecture — global tokens define raw values, alias tokens map semantics (color-primary), and component tokens consume aliases. Swapping only the alias layer changes the entire brand appearance while components stay unchanged. This separation ensures that component code remains brand-agnostic and scales effortlessly.

Q: How do you implement brand switching in Angular?

A: Apply a brand class or data attribute to the root element and scope CSS custom property overrides to that selector. Angular services manage the active brand token, making runtime switching instant with no page reload. Use APP_INITIALIZER to load brand tokens during application bootstrap for zero startup latency.

Q: Can Figma support multi-brand design systems?

A: Yes — Figma variable modes let you define multiple brand sets within one variable collection. Designers switch modes to preview different brands on the same component, keeping design and code in sync. This ensures designers and developers work from a single source of truth.

Q: What is the difference between theming and white-labeling?

A: Theming changes visual presentation (colors, typography, spacing) for different products or clients. White-labeling goes further, also customizing logos, copy, and sometimes component behavior, typically for B2B SaaS or agency delivery. Multi-brand design systems support both use cases through token layering and strategic component composition.