Design Tokens

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

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.

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.

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.

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.

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.

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.