01) Design Tokens

Date: 2021-10-11

Status

Accepted

Context

Design tokens are values that represent the style of the design system and its UI elements. They are organized in a way that makes it easy to maintain a scalable and consistent visual system for UI development. Most of the current and legacy design decisions are kept in wikimedia-ui-base.css, in a technology-specific format. They are also available in .less.

For Codex:

• We also want to keep providing the design styles separately from the UI elements
• We want the tokens to be the source of truth for all Vue components
• We want to provide the tokens in different output formats

Considered Actions

Technology-specific token definition

This option means specifying tokens in a format understood by CSS, Less or Sass (SCSS).

Advantages

• Good IDE support for use of variables
• No need to use any additional tools

Downsides

• No native support for structure - one has to decode the structure from the name of the variables
• Entails manual work to support several output formats
• Limited possibilities of providing specific information about the tokens

Technology-agnostic token definition

This option means specifying tokens in a generic format (e.g. JSON/YML) which have to be converted to files as understood by specific technology (CSS, Less, Scss etc.)

Advantages

• Shows on the conceptual level system design comes before concrete implementation
• Allows us to store additional information (e.g. comments) alongside the token values
• Allows us to support different technologies at the same time
• It is the future-proof option - we can easily add more output formats when/if we need them

Downsides

• Possibly bad IDE/IntelliSense support

Decision

We decided to go with the technology-agnostic token definition. We choose to use style-dictionary to consume and convert the tokens for us.

Consequences

We achieve agnosticism on the token level and can support many target formats without manual work thanks to our tool of choice.