Design Tokens for Mesh have just been released!
Skip to content

Design Tokens

Design tokens represent design decisions, stored in a way that can be understood by all kinds of platforms, languages, and most importantly, people.

What are design tokens?

Design tokens are design decisions, stored in a way that can be understood by all kinds of platforms, languages, and most importantly, people. In Mesh, they enable fast, reliable application of brand and best practice when building digital experiences.

Typically, design tokens consist of a name and a value (known collectively as a key-value pair), but can be structured in a way that creates a deep and interconnected network of answers to common styling questions. Their purpose is to act as a single, intuitive source of truth, meaning they can be universally distributed, maintained, updated and referenced.


Functionally, design tokens are variables - their values are dynamic and changeable, depending on their context. In Mesh, we provide a range of tokens that adapt to various brand expressions, design choices or usability considerations.

Understanding the value of tokens

By lifting these design choices out of a codebase or platform (like React or Figma), inconsistencies between platforms are more easily identified or addressed, without any one platform needing to act as a source of truth. The design system then becomes a collection of individual decisions, with each platform, codebase or language instead becoming an expression of that system.

While the initial implementation of tokens in Theme v7.0 is focused on application of color, color is only a visual proxy for the infrastructure created to support it. We have also introduced a base selection of tokens for spacing, breakpoints, container width, border radius and border thickness.

In the long term, we intend to tokenise most styling decisions; including typography, elevation, motion, and miscellaneous or platform-specific expressions. Together, these will reinforce our branding capacity, build resilience in our ways of working, support iteration of our products and platforms, open up new business opportunities, and apply nib’s core values across our digital ecosystem.

A brief history of tokens in Mesh

Mesh was originally designed to enable whitelabeling of nib’s products and services, without the added cost of having to maintain parallel experiences. A single digital product could then be themed infinite ways, with optimisations - driven by data and research - able to be easily rolled out to all applications equally and at minimal cost.

In a manner of speaking, Mesh’s React library has always included a limited scope of style variables, represented in prior versions of our Theme component. However, as Mesh has been integrated across the business, that particular scope and system has become rigid as the cost of refactoring for changes has grown.

More recently, as our scope of brands has grown and digital accessibility has become an everyday consideration, selectors such as brandBase have become difficult to rely on. Applied to text, this token might provide an accessible level of contrast for nib’s trueGreen, but would not be suitable at all for a partner brand whose primary color might be pink or yellow.

As we explored how to solve these false equivalencies in the color space, Figma’s introduction of Variables accelerated the conversation. We recognized that having a flexible but prescriptive system of tokens, with a clear hierarchy and ability to resolve unknown values, would enable us to iterate confidently, embrace new brand palettes rapidly and accessibly, and more easily onboard new designers, developers, contractors or stakeholders to building products with Mesh.

Basic token classes

Mesh contains three classes of token: common, theme and primitive. Primitives are not typically needed for Mesh users, and exist primarily as a base layer for theme tokens.

Common tokens

Common tokens apply universally and consistently across all Mesh-supported environments. They are not configurable per brand, and typically represent functional values, such as spacing, breakpoints or container widths, or store common values for convenience.


Theme tokens

Theme tokens are semantically named for the context in which they are applied, rather than their assigned value. Each theme token’s value is fluid, depending on the brand or mode applied.


Note that brand or mode identifiers are not typically included in a token reference, and are only included here to specify the brand or mode applied.

To ensure flexibility as new tokens are added or modified in future, Mesh uses a model where branded values overwrite a base layer of default (or core) values. If a brand mode does not declare a particular token, it will return either its parent or default mode’s value, or the default core value. This ensures that a value is always present.

Component tokens are a sub-class of theme token. They are still semantic in name and nature, but are specifically scoped to the component they’re named for, and should rarely be required outside of that context. They generally aren’t surfaced for consumers of Mesh, as they’re integrated into their respective component packages.

Primitive tokens

Primitive tokens are the raw building blocks for branded themes. They house our in-house or partner brands’ digital style guidelines in a format consumable by Mesh. Given the broad scope of brands we support, a brand’s primitives folder might contain any number of values, and no equivalency should be presumed between brands.


Note that primitive tokens do not presently contain a brand reference. Most intended applications presume a single brand across an entire page or experience.

At present, primitives are not surfaced for consumers of Mesh, as they are non-semantic and only appropriate for direct use in bespoke, single brand applications.

Numeric naming of color primitives

For convenience, we append primitive color token names with a number according to their **Lightness (lch) value.** The **lch** color space is based on human perception of color, and can be used to help estimate visual contrast between elements.

For example, when applying a foreground color on a background of nib.primary.200, any primitive with a lightness value of over 700 (e.g. nib.primary.830) should provide sufficient contrast to meet WCAG’s AA (4.5:1) guideline threshold.

Understanding brands and modes

As variables, it’s important to understand that tokens don’t always correspond to a single value. Values can be dynamic, changing based on the context. In Mesh, that context is typically defined by two parameters, working in tandem: brand and mode.

In the context of Mesh, ‘brand’ refers to a collection of tokens, modes and values relating to the brand identity one of nib’s partners, subsidiaries or sub-brands.
A single expression of a brand. Each brand contains a default mode, and typically one or more alternate modes.

While brand is a collection of modes, both brand and mode need to be identified to return a value, with examples in the table below. Note that if a mode is not declared, the ‘default’ mode value will be returned.


Common modes

Note that common tokens exist independently of brand, as they apply universally across Mesh. They may, however, still contain one or more alternative modes. One such example is our spacing scale - in future, we intend to support a ‘compact’ mode, which contains an alternative set of values for each ‘stop’ within the scale.

Color modes

Color is simultaneously one of the most subjective and semantic tools we have to enhance digital experiences. Usability considerations like contrast and color theory are balanced with brand palettes, aesthetics and sentiments, so a token-based color system needs to provide both guidance and freedom of expression.

With digital accessibility becoming a key consideration across our assets, maintaining sufficient contrast between foreground elements and their respective backgrounds is fundamental. To avoid a cascade of unpredictable contrast relationships, we chose to ‘fix’ background tokens to a narrow spectrum of variations for each mode, enabling a broader scope of accessible foreground and border choices.

To that end, tokens can be considered to represent structural and semantic choices, with modes enabling a more expressive application of brand, sentiment or aesthetic. More simply, selecting a color mode can be viewed as changing your background color, with foreground token values changing automatically as a result.
“...selecting a color mode can be viewed as changing your background color, with foreground token values changing automatically...”

Modes are applied differently within each platform, but generally operate as a ‘wrapper’ around any given element(s). Any elements contained within that wrapper will apply the nominated mode, and mode wrappers can be nested multiple times.

Transparent or fill-less elements

Note that transparent elements or elements without a background fill (such as text) can have a mode applied, changing their value without changing the background onto which they are placed.

Use care when applying modes in this way, as it may compromise the accessibility of your experience. Ideally, modes should only be applied to content with a background fill.

Other mode types

In future, modes may be used for purposes other than colour - like custom spacing, responsive type, low motion or high contrast. In those cases, modes may be applied in parallel or in series, but this will be documented as those needs arise.

Supported platforms

Tokens are currently supported by the platforms listed below.

PlatformStatusResources & Notes
Using Tokens in Figma
React (Web)
Supported (v 7.0+)
Using Tokens in React
CSS Framework