Codex01) 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.