Summary
Design tokens are representing systematic design decisions, on which the style and the behavior of components & patterns are based on exclusively.
In the words of the W3C Design tokens community group: “Design tokens are a methodology that allows sharing stylistic pieces of a design system at scale”.
Over the course of the last couple of years architectural decisions on the use of centralized style(sheet) variable definitions (started as WikimediaUI Base variables, now referred to as design tokens) have accumulated in a number of tasks and places in MediaWiki and Wikimedia resources.
This task aims to be a central place collecting and deciding on open questions for the Wikimedia Design System design tokens and its use in the upcoming shared component library T288980.
Goals of design tokens
- Consistent values in development
- Set of predefined, centralized, limited and traceable design decisions as
- Single source of truth for design to development handover
A nice write-up on design tokens can be found at CSS-Tricks with feedback of term creator Jina Anne:
With design tokens, you can capture low-level values and then use them to create the styles for your product or app. You can maintain a scalable and consistent visual system for UI development.
Considerations
1. Design & definition
1.1 Design tokens definition in DS governance model
Wikimedia Design System Governance workflow model, exemplified on component addition with tokens steps.
The used tokens per component/pattern are defined in design step, with handover and evaluation by developers. The naming is set around guidelines and with development focus., see abstraction levels and naming rules below.
1.2 Design tokens abstraction
What kind of abstraction granularity is most productive from those options:
- Foundational (& legacy themed) > Base/Grouped > Component overrides
- Globals > Alias > Each Component property with a specific component token (all styles)
T266688: Evaluate variables aka tokens abstraction
Decision: We've decided to go with 1. as it promises less overhead in creation and maintenance and slightly less lookup work for developers debugging.
2. Tech considerations
2.2 Repository or “where they live”
Currently in Wikimedia Foundation, WikimediaUI Base as separate library comes in two stylesheet representations (CSS and LESS) in order to be used by MW core & RL (LESS), but also to enable usage in other frameworks like Bootstrap.
Proposal and decision: Monorepo with sub-package(s) tokens defined in JSON source format and icons in SVG source format in different stylesheet outputs: CSS, LESS, Sass. Further details in T292255: Where should design tokens live? Separate repository or monorepo with Design System?.
2.3 File source format
What file source format is most productive/least overhead/least maintenance?
Technological format choice (CSS/LESS/Sass vs JSON) with our platforms besides web – iOS, Android, kaiOS – has been resolved in T277616: Clarify technical choice with product team needs for design tokens/variables.
Outcome: Stylesheet variable definition is sufficient.
- Revisited decision**: In the Vue.js WMDE <> WMF task force we've agreed on JSON format
2.4 Naming rules
See section in CSS coding guidelines on variable naming.
Proposal and Decision: property-object-or-application[--modifier]
3. Presentation
3.1 Design tokens visualization
How to simplify design, handover and QAing of tokens?
Proposal and Decision: Aim for simple style visualization T289727
Beyond having those simple style decisions as Figma predefined attributes or objects? (to clarify later)
3.2 Design tokens and impact on themeability
We have to ensure that the tokens are able to be used not only in the component library, but also in MediaWiki core for ensuring a centralized visual language.
(WikimediaUI Base tokens usage currently)
Proposal and decision: Monorepo with sub-package(s) tokens and icons in different stylesheet outputs: CSS, LESS, Sass. To be imported as dependency in different repos.
Implementations elsewhere
Decision
At the October 2021 Design Systems Taskforce Summit it was decided that
Design tokens will be formatted in JSON, rather than a technology-specific format, so we can support many formats moving forward. Codex will use Style Dictionary to convert the tokens into various formats for use.