Token Guidelines

[gfellerph]

We should have a comprehensive documentation of our token system which explains the basic concept and the architecture we're using.

Old text

Basics

Design tokens — or tokens, for short — are design decisions, translated into data. They’re ultimately a communication tool: a shared language between design and engineering for communicating detailed information about how to build user interfaces.

Tokens consist of values needed to construct and maintain a design system, such as spacing, color, typography, object styles, animation, and more. They can represent anything that has a design definition, like a color as a RGB value, an opacity as a number, or an animation ease as Bezier coordinates.¹

Other resources:

• Atlassian Design Tokens
• Salesforce Lightning Design Tokens
• Material Design Design Tokens
• W3C Design Token Community Group

Architecture

Tokens are categorised into 3 groups: core, semantic and component tokens. Each group has it's specific purpose and rules. The core and semantic layer are meant to be internal to the Design System, the component layer is intended to be used by the implementation. This enables introducing changes to the core and semantic layers without breaking changes in the component layer.

Core layer

Core tokens are the most basic tokens and represent concrete values, for example yellow = #ffcc00 or size-16 = 16px.

• Don't assign semantic names to core tokens. Do yellow = #ffcc00 instead of brand-color = #ffcc00. brand-color is a semantic name and belongs in the next group
• Core tokens can reference each other in composite or derived tokens: sandgray = #050400 can be reused for a transparent variant with sandgray-alpha-50 = rgba(sandgray, 0.5)
• Core tokens should not be aliased. When there's a definition for sandgray = #050400 there should not be another core token with the exact same value, e.g. othergray = sandgray or othergray = #050400. This would unnecessarily increase the number of tokens
• Core tokens should not be referenced or used directly in any application since they represent static values that are intended to be referenced by either semantic or component tokens

Mapping layer (Semantic tokens)

Semantic tokens represent changes in design decisions across different environments, for example the body font-size that grows larger with increasing browser size. The semantic layer can also be seen as a mapping layer between the core and the component layer. It reassigns tokens to the correct values based on the current environment, for example styles for an external post themed page on a mobile device in dark mode.

• Semantic tokens should be named around design concepts like brand-color or font-size curves (TODO: better define what design concepts are)

  Example of a responsive font size token definition in the semantic layer, referencing three different core tokens:

  Token	Mobile	Tablet	Desktop
  font-curve-base	size-16	size-18	size-20

• Semantic tokens can reference core tokens as well as other semantic tokens

• Semantic tokens should not be referenced or used directly in any application since they represent changing values. In any given environment, a semantic token is never guaranteed to be the finally desired value since it could be referenced and overridden by another semantic token

• Tokens from the semantic layer are intended to be implemented in an automated process

• Semantic tokens should be grouped by environment: modes (light/dark), themes (post/subsidiary X/subsidiary Y), devices (mobile/tablet/desktop), channels (internal/external).

• It should be possible to extend or reduce semantic groups or their environments and re-map values without introducing breaking changes to the system. This is only possible if implementations use an automated process to ship semantic tokens and never directly reference semantic tokens from within components

Implementation layer (Component tokens)

On the last layer, component tokens are tied directly to components (or utilities) and their properties.

• Naming: Component tokens should be named according to the property of a component, for example button-padding-left = interactive-padding-left. The naming of properties should be as platform agnostic as possible (foreground-colour instead of just colour which would be CSS specific and not self explanatory in a token context since it could mean border colour, background colour or text colour).
• Scoping: Every component should have it's own set of tokens, component tokens should not be shared between components (see Component Token Naming #3356)
• Component tokens should reference semantic tokens if their value is expected to change based on the environment they are used in. If the value is static, component tokens can also reference core tokens directly
• Aliasing: Component tokens should never reference another component token. Component tokens are not intended to be defined on the page (in the web implementation). If you find yourself in the situation where it would make sense to alias a component token, refer to the same semantic token instead
• Single source of truth: Avoid creating tokens that are only used in one implementation (figma only or code only). These tokens violate the single source of truth rule or violate the aliasing rule of component layer tokens. Exceptions to this rule can be agreed on if tokenisation is a big benefit but implementation systems are not compatible (font definitions in figma and CSS which work almost completely opposite)

New text

Design Tokens: A Guide for Building Consistent and Scalable Interfaces

Basics

Design tokens — or simply "tokens" — are a way to encapsulate design decisions into data that can be consistently shared and applied across different platforms, technologies, and tools. They serve as a communication bridge between design and engineering, enabling teams to implement UI elements with precision and consistency. By converting visual styles into structured data, design tokens help maintain a design system that is flexible, scalable, and easier to manage over time.

A token represents an atomic value that’s reusable and foundational to the design system, such as colors, spacing, typography, borders, animations, etc. These values can be stored in a format (e.g., JSON, YAML, or CSS variables) and used across web, mobile, or any other platform. For example:

• Color: primary-color = #ffcc00
• Opacity: overlay-opacity = 0.7
• Animation: ease-out = cubic-bezier(0.25, 0.8, 0.5, 1)

Design tokens provide a single source of truth that ensures consistency across a product's entire interface, no matter where or how it’s implemented.

Further Reading & Resources

• Atlassian Design Tokens
• Salesforce Lightning Design Tokens
• Material Design Design Tokens
• W3C Design Token Community Group

Design Token Architecture

Design tokens are generally categorized into three key layers: Core, Semantic, and Component tokens. Each layer has a specific role within the design system, ensuring that tokens are scalable and adaptable without breaking downstream implementations.

1. Core Tokens

Core tokens represent raw values or base design elements such as colors, sizes, or font properties. These are the fundamental building blocks that don’t contain any context or semantic meaning—they are purely the static, unchanging values that are used throughout the design system.

Guidelines for Core Tokens:

• Core tokens define base values (e.g., yellow = #ffcc00 or size-16 = 16px).
• Core tokens should not have semantic names. For example, instead of naming a color brand-color = #ffcc00, it should be named yellow = #ffcc00.
• Core tokens can reference each other. For example, a transparent version of sandgray can be defined as sandgray-alpha-50 = rgba(sandgray, 0.5).
• Core tokens should be unique and not aliased (i.e., avoid multiple names for the same value).
• Core tokens are internal to the design system and should not be used directly in applications. They are designed to be referenced by higher-level tokens (semantic or component tokens).

2. Semantic Tokens (Mapping Layer)

Semantic tokens define contextual meaning for design decisions, mapping core tokens to more meaningful concepts. These tokens account for dynamic variations in design based on environment, theme, mode (light/dark), or platform (mobile/desktop). Semantic tokens create an abstraction layer between core values and components, allowing flexibility without direct exposure to the underlying values.

Guidelines for Semantic Tokens:

• Semantic tokens capture design intent and map core tokens to specific design concepts (e.g., brand-color, font-size-base).

• These tokens can adapt based on the environment, such as viewport size, themes, or modes. For instance, a semantic token for font size might change across different devices:

  Token	Mobile	Tablet	Desktop
  font-size-base	16px	18px	20px

• Semantic tokens can reference both core tokens and other semantic tokens, ensuring flexibility for dynamic environments.

• Semantic tokens are usually not directly referenced in applications; instead, they are applied via an automated process (e.g., theming or responsive design frameworks).

• Semantic tokens should be structured in groups based on environment factors such as themes (cyber security/cargo), modes (light/dark), devices, and channels. For example, there could be separate tokens for different subsidiaries, or external and internal platforms.

Example:

• In dark mode, a background-color semantic token might map to core-color-black, while in light mode, it might map to core-color-white.

3. Component Tokens (Implementation Layer)

Component tokens apply the design tokens to specific components in the UI, like buttons, input fields, or cards. These tokens reference semantic tokens or core tokens based on the component’s design needs. By tying tokens directly to component properties, we ensure that the design system can be applied consistently in any context or platform.

Guidelines for Component Tokens:

• Naming: Component tokens should reflect the specific property of a component, using platform-agnostic terminology. For example, instead of using CSS-specific terms like color, use terms like button-background-color or card-border-radius.
• Scoping: Component tokens should be scoped to the specific component. Each component should have its own set of tokens. Avoid sharing tokens between components to maintain flexibility and reduce dependencies.
• Referencing: Component tokens should reference semantic tokens when their values need to adapt based on the environment (e.g., button-padding-left = interactive-padding-left). If the value is static, they can reference core tokens directly.
• Avoid Aliasing: Component tokens should not alias or reference other component tokens. If needed, refer back to the corresponding semantic token.

Cross-platform Considerations

One of the most powerful benefits of design tokens is their ability to ensure consistent design across multiple platforms, such as web, mobile (iOS and Android), and even desktop applications. By creating a universal design language, teams can maintain a cohesive look and feel across all touchpoints, while still allowing for platform-specific nuances.

Considerations for Cross-platform Design:

• Platform-specific adjustments: While the same design tokens can be used across platforms, there may be cases where certain adjustments are necessary (e.g., mobile uses a different typography scale or spacing system). In such cases, tokens should be designed with enough flexibility to adapt to platform-specific needs while maintaining overall consistency.

  Example: On mobile, touch targets might require larger padding, so a semantic token for padding could have platform-specific values:

  Token	Web	iOS	Android
  button-padding	12px	16px	14px

• Environment-specific tokens: By defining tokens that are tied to environments (e.g., dark mode for mobile), teams can ensure that UI components adapt appropriately without manual intervention.

  For instance, a dark mode button background might change across platforms, but it’s still managed through tokens:

  Token	Web	iOS	Android
  button-background-dark	#333333	#222222	#444444

• Tooling integration: Make sure your tokens are structured and exported in a format that works seamlessly across different platforms. Tools like Style Dictionary or Theo can help convert design tokens into platform-specific formats such as SCSS, XML, or JSON, ensuring that each platform gets the correct values.

Accessibility and Design Tokens

Design tokens play a crucial role in ensuring that a product is accessible to all users, as they help standardize the application of key accessibility principles such as contrast ratios, font sizes, and motion preferences. By using tokens thoughtfully, accessibility can be "baked in" to your design system.

How Tokens Support Accessibility:

• Color contrast: Using tokens to define color combinations for text and backgrounds can help ensure the contrast meets accessibility standards (e.g., WCAG guidelines). For example, a semantic token like text-on-primary can reference a core token with a high-contrast color value. You can then adjust these tokens based on dark or light mode requirements to meet the appropriate contrast ratios.

  Example:

  "text-on-primary-light": "#000000",
  "text-on-primary-dark": "#FFFFFF"

• Scalable typography: Defining font sizes, line heights, and spacing as tokens allows for easier scaling across devices, ensuring readability at different screen sizes. Tokens like font-size-base or line-height-large can be adjusted responsively across platforms, improving accessibility for users with visual impairments.

• Reduced motion: Some users prefer reduced animations for accessibility reasons. By creating tokens that control animation properties (e.g., animation-duration or animation-ease), you can easily adjust motion across the interface in response to user preferences.

  Example:

  "animation-ease-reduced": "cubic-bezier(0.25, 0.8, 0.5, 1)"

• Consistent touch targets: Design tokens for spacing and padding ensure that interactive elements like buttons or links maintain appropriate touch target sizes, which is critical for accessibility on mobile devices.

By integrating accessibility considerations into your design tokens, you can create a more inclusive product that meets the needs of all users, regardless of ability.

Summary

Design tokens serve as the foundation of a well-structured design system, promoting consistency, scalability, and flexibility. By separating tokens into layers—core, semantic, and component—we create a system that is not only adaptable to changes in design but also easily maintainable. Tokens help ensure cross-platform consistency, enable easier adaptability for different environments, and support accessibility, making them essential for building user-centric, inclusive products.

Footnotes

1. Design tokens - Spectrum: https://spectrum.adobe.com/page/design-tokens/ ↩

[Vandapanda]

Started something on experience hub but didnt get to finish it yet, maybe we can combine that with the text above

[gfellerph]

Added as task in #3448