Nov 9, 2022 · 8 min read

Lost in customization

Design a flexible customization architecture for multi-brand design systems.

Ideally, a design system should optimize product design and development in a company, but what happens when it has to support multiple brands evolving their visual identity and digital products in different directions? How can yet still facilitate them to achieve their objectives without being lost in customization?

Charlotte: I just don't know what I'm supposed to be.

Bob: You'll figure that out. The more you know who you are, and what you want, the less you let things upset you.

Lost in translation

Being unable to adapt and scale a one-source-of-truth system based on the different brand requirements can lead to ejecting users and going custom (or creating a system per brand), losing the benefits that a unified artifact brings for building digital products in the company.

Scene from the movie Lost in translation where Bill Murray is looking at multiple colored cloth tiles in the ground.

Fig. 1 - Choosing the right way to evolve your system.

That's why it's crucial to design a customization architecture that is flexible enough to cover current and future requirements. The same as a mono-brand system centralize the design decision around a single abstraction layer, multiple centralized layers will still save your company tons of money.

The customization strategy

When I worked in DXC's Halstack design system, part of the SaaS offering was a visual tool to enable customers to customize the system components and create a theme to later apply to their product implementation. There were two different strategies:

  • A highly opinionated theme generator: Was meant for simple brand customizations. There were few inputs in the theming tool per component primarily focused on color (You provided a primary color and the generator, for example, auto-calculated the values for the :hover or :active states).

  • A flexible theme generator: meant for brand guidelines complete alignment. Covered all the visual properties we thought every component should have (That means having more than 80 design tokens only for the button component).

The reason to be of your design system, its users, and the products it serves is going to determine the way you design your customization strategy. For example, in a house of brands(1) organization structure, the best plan of action would probably be to pick the most visually complex brand and try to accommodate the rest of them to the needs of the first one.

Be aware that the level of customization your system provides is directly proportional to the time-to-production and complexity you'll need in your theme and component layers. A clear early-on strategy will save your design system source code from being refactored when requirements increase.

The three dimensions of a component

When looking at a user interface component living in a design system, we can break it into three different dimensions:

  • Structure: The elements that are part of a component (HTML)

  • Appearance: How a component and its elements look (CSS)

  • Behavior: What the component does (JavaScript)

Usually, in a mono-brand design system, those three dimensions are part of the agreement between the different product teams and their needs. When thinking about customization, the consensus should shift from three to two dimensions: structure and behavior.


Ensure that structure and behavior component definitions are transparent and open for every system user, which is where all the stakeholders and product teams should be on the same page. Having "what ifs" per brand in those dimensions are something you should consider avoiding from early on.

Component structure and behavior can be defined as low-level UI elements (Primitives), a highly reusable abstraction of UI patterns, or live as a higher-level abstraction that brings shared functionalities between the different products the design system has to serve. (Or both)

In addition, component props can be highly-opinionated or very flexible depending on the philosophy or maturity of the system (This topic is a whole new article).

What brings value is having one single source of truth where every element defined on the structure dimension have multiple visual properties that can be potentially customizable. This is the "appearance dimension" where we can apply the power of design tokens to control differences between brands.

Domains, roles, contexts and types

In order to introduce the design tokens into the design system customization strategy, we need to understand the different domains, roles, contexts, and sub-contexts.


Multibrand design system tokens can be divided into two domains:

  • Global: Brand-independent tokens.

  • Local: Brand-dependant tokens.


The role of the token in a design system can be defined as in which abstraction layer of the available spectrum is placed.

Diagram that shows how a token in a design system can be more abstract or component-oriented.

Fig. 2 - Token abstraction level spectrum.

From component-agnostic to component-oriented, multiple token layers give more control over the scope of the token value within the system. Scope control also applies to system customization, allowing changes to permeate from different layers to change specific aspects of the components in the local domain.

You're going to need at least two layers of abstraction to be able to swap token values. For example, a complete component-agnostic layer can store the brand-specific values and then a middle layer can map those values into the components.

Diagram that shows how a token value can be swapped between brands.

Fig. 3 - Token value swap between brands

In Mística we call the component-agnostic layer "constants" (Since the token name and value is unique for each brand) and the middle layer "variables" (It always has the same name and the value is taken from the different brand constants).

Component-oriented tokens offer a "self-service model" (2) and more control over the customization scope, but you should use them sparingly; tokenizing every component attribute, state, and variant will play against you when the system scales.

Diagram that shows for areas where the tokens of a system can fall depending of how easy or hard are to define/mantain.

Fig. 4 - Token definition / maintenance matrix.

As shown in figure 4, component-oriented and local are the hardest to define and maintain, followed by the component-oriented globaltokens. Each quadrant tokens can co-exist in the system, but placing the highest percentage in the top-right and top-left quadrants is more convenient.

Context and sub-context

The different environment variables that can make the token value change:

  • Platform: Web, iOS, Android, etc.

  • Viewport size: desktop, tablet, mobile, watch, etc.

  • Color scheme: light, dark, high contrast.

  • Other...


A classification applied to the value of a token (3). The different token types will define which visual properties are available for customization, a token's type list within a design system can be as small as color or include properties like filters, transitions, or gradients.

Audit the different brands that live / will live in the system to extract the token types you'll need. Be also aware that opening some visual properties for customization may impact others (If a brand increases the font size in specific components, the vertical rhythm will be affected, so they'll need to change spacing values too).

(3) Design Tokens Community Group. DTCG Glossary

Arranging token data

To better understand the structure of each brand theme inside the system, it's valuable to cross the different domains, contexts and types.

For example, a transversal font size value across the whole system (Global) can change its value depending it is displayed on a desktop or a mobile screen. A text's font family can vary depending of brand and the platform (Using the native families in iOS or Android devices).

This token data arrangement can be done in a simple table and provides information about which token types will change their value depending on the different contexts.


Token typeDomainPlatformViewport sizeColor scheme

You can increase the complexity of the table by adding the different roles that your tokens have, the sub-contexts that apply to your products, the value for each brand, etc. It will give you a detailed view of all the layers involved and help you to embrace the complexity.


Token nameToken typeDomainBrandLight schemeDark scheme

It may seem pretty obvious at first (Oh... a table, what a genius), but doing this exercise will answer questions you may not have at the beginning, and will provide more confidence when it's time to implement your whole architecture.

Design tokens dendrogram

A dendrogram is just another way to visualize the system tokens structure. From the domains to the values, each ramification represents the different types and contexts your tokens will fall into.

Diagram showing the theme structure for a specific brand in the local domain.

Fig. 5 - Theme dendrogram for a specific brand in the local domain.

Although they visually explain the theme structure better, one of the pitfalls of dendrograms is the inability to compare different brand values. This design tokens architecture representation mostly focuses on building JSON files.

There's an example in Amazon's Style Dictionary repository built for multi-brand and multi-platform that puts this theory into practice, creating specific folders for the brands, platforms and global tokens.

Diagram showing the tokens structure for Amazon's multi-brand and multi-platform.

Fig. 6 - Amazon's multi-brand and multi-platform tokens structure.

In this particular case, you cannot change, for example, the values of the tokens defined in each platform by brand.

Each design system tokens architecture and customization strategy is unique, before starting with the implementation I recommend stepping into visualizing how the theme structure looks and mapping the different planned token values with your system contexts.