Token Guidelines

[gfellerph]

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

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.

[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

[sandra-post]

@gfellerph FYI content partially available in WIKIT / Design Tokens / Overview (content mainly from #3371 )