Building better products with a design token pipeline
By: Lukas Oppermann
Tags: Design, Design Systems, UX, Ts, Product Design

Option Design Token

Option design tokens represent ALL available values within your design system. All colors, font sizes and spacings should be represented as an option design token.

The option token definition is the only place where raw values like 8px are allowed.

Option design tokens should not be used directly but only referenced by decision design tokens.

An option design tokens name is an abstract representation of its value. It does not suggest any use:

both color-blue-500 or typescale-font-size-sm are fine names for an option design token

or are fine names for an option design token color-cancel-red is not a good name, as it implies the color should only be used for cancel action

With all options at hand, fitting new components into the design system gets much easier. Just pick and choose which of the available option design tokens fits best. Creating and using decision design tokens that reference option design tokens have another benefit. Your components update automatically when the options change.

Decision Design Tokens

Decision design tokens represent a context in which a referenced value is used.

They never hold a raw value (e.g. 8px ), but only ever reference an option design token like $color-blue-500 .

The name of a decision design tokens represents how and in what context to use the token.

button-cta-background-color or image-description-font-size both describe what the token is (how to use) and in what context.

or both describe what the token is (how to use) and in what context. main-background in contrast is a bad name. Neither do we know if it is a color, image, etc. nor what context we should use it in.

Following this approach your token names are a small part of your documentation. Token users (mostly developers) can understand what the intended use of a token is.

This prevents them from mixing up values and allows them to flag missing / misused tokens.

Additionally, using decision design tokens allows you to restrict changes to a context. You can change the background of the CTA-button on your landing page, without influencing the rest of the product.

This allows for a good balance between consistency / maintainability and flexibility.

Documentation & storage

Design tokens live in a technology agnostic file (like json or yaml ), stored in a central location accessible by all teams. This lifts them out of your design file and into the middle of the product development process. Design tokens "belong" to everyone, they are a tool that all can and should use.

The token file is meant for everyone, so adding documentation is encouraged. This is best done by adding a comment , description or remarks property to a token. As of now there is no standard for how to name it.

documenting design tokens

'colors': {

// ...

'danger-red' : {

'value': '#F52C10',

// depending on your toolset any of the below may be supported

// otherwise they are normally ignored and should not create an error

'comment': 'This color is only use for error messages',

'description': 'This color is only use for error messages',

'remarks': 'This color is only use for error messages',

'deprecated': 'This color is deprecated, use core-red instead'

}

}

This can be helpful to mark tokens as deprecated or experimental. You can also add usage info that elaborates on the info provided by the name. E.g. This color may only be used for error messages .

Conclusion

Use option design tokens to define ALL available design values in your product

Use decision tokens to apply option design tokens to a context

Name your tokens in a way to document their intended use and context

Add additional documentation to the design token file

Specifying and documenting with design tokens

Working with a design system most of your work is composing components into layouts. At this point most of the documentation work has already been done. You only need to specify the spaces around the components, if this is not done on a per component level.