Guidelines

Overview

Introduction

Foundations are our smallest essential building blocks that form the base of visual consistency of our design system. These foundations serve as the backbone, ensuring every design maintains the same look and feel while being adaptable across various use cases. They also enable easier maintainability and flexibility if we want to adjust a central part of our visual branding.

What Are Design Tokens?

Design tokens are the smallest building blocks of our design system. They store design decisions like colors, fonts, and spacings as reusable variables. They bridge the gap between design and code, ensuring consistent implementation across use cases without hardcoding values. Design tokens create a single source of truth for all our design-related properties, enabling us to easily modify a value centrally, ensuring scalability.

Types of Design Tokens

• Color
• Typography
• Layout
• Spacing
• Border
• Shadow
• Opacity
• Transition

How We Use Design Tokens

Design tokens are embedded in both design and development workflows, acting as the bridge between design tools and the final code. Designers use tokens within Figma, while developers reference tokens in the code through Tailwind and CSS variables.

Best Practices for Using Tokens

Always reference tokens instead of hardcoding values to maintain consistency. Use semantic names that describe the token’s purpose, and ensure accessibility through thoughtful token choices (e.g., color contrast for text).

Further reading

If you’d like to learn more about design tokens, explore the following links:

• Tokens in Design Systems - Nathan Curtis
• Using design tokens to promote collaboration and maintainability of a design system
• An example of design tokens in a live design system - Lightning Design System

Naming

Description

To create a modular, consistent and scalable token system we created and agreed on a set of rules that explain how tokens are named.

General Naming

• Only use lower case
• Always use singular naming (i.e. text-primary, not texts-primary)
• Separate words with a dash (-)

Token Layers

Layer 0: Pure Value

These are the pure hex color values and should never be used!

Layer 1: Core Token

The most basic building blocks that all semantic tokens are directly linked to. These are not communicating design decisions and should be only applied in rare cases, where there is no semantic token available or planned.

Layer 2: Semantic Token

The tokens that are communicating design decisions and are linked to a specific use case. They should be easy to understand, versatile, and easy to apply in everyday usage.

Token Naming

Naming structure

Namings should be easy to understand and clearly reveal the purpose at a glance. To ensure consistent and systematic naming, we follow these guidelines ([ ] = optional) :

Examples

Sizes

For sizes, we are using a T-shirt scale. This enables technical, but also non-technical people to understand the differences and how they relate to each other.

Our sizes are having always a minimum of 2 characters. So sm (small) instead of just s.

After xs or xl the scale is extended by adding a number before the value. 2xs instead of xxs, 3xl instead of xxxl

Scale

States

Our state naming represents 1 to 1 the naming of pseudo-classes in css, to enable smooth collaboration between developers and designers in their everyday business

hover

Matches when the user interacts with an element with a pointing device, but does not necessarily activate it. It is generally triggered when the user hovers over an element with the cursor (mouse pointer).

active

Represents an element (such as a button) that is being activated by the user. When using a mouse, “activation” typically starts when the user presses down the primary mouse button.

focus

Represents an element (such as a form input) that has received focus. It is generally triggered when the user clicks or taps on an element or selects it with the keyboard’s Tab key.

disabled

An element is disabled if it can’t be activated (selected, clicked on, typed into, etc.) or accept focus. The element also has an enabled state, in which it can be activated or accept focus.

other states

In the case other states are needed please only reference and add states that are available as css pseudo-classes.

Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes

Status

success

Used to display a positive completed action or status.

warning

Used to display information that needs the user’s attention and may require further action.

critical

Indicates a problem or error that have to be resolved before the user can move forward.

Light- & Dark mode

light (default)

Our default theme is not referenced in the name of the token.

darkMode

Components or colors that have an optional dark mode version will be marked by the single word dark.

Numbers Scale

In use cases where it’s less about the size of different objects (for example color), we can apply this numbers scale.

Variant

The variant scale is best to be used when:

• There is a minimal amount of choices (max. 4)
• You want to strongly indicate the hierarchy or context