== 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 [[ https://www.w3.org/community/design-tokens/ | 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 [[ https://css-tricks.com/what-are-design-tokens/ | 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
[[ https://www.figma.com/file/cnbxl3nG6CKpjaTSjXTwQk/Wikimedia-Design-System-(DS)-%E2%80%93-Governance-model-(component-addition-process)?node-id=0%3A1&viewport=98%2C379%2C0.25 | Wikimedia Design System Governance workflow model ]], exemplified on component addition with tokens steps.
{F34663046 width=50%}
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?
1. Foundational (& legacy) > Based/Grouped > Component overrides
2. Globals > Alias > Component (all styles)
{T266688}
=== 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.
Details in T292255
**Proposal**: Monorepo with sub-package(s) tokens defined in JSON source format and icons in SVG source format in different stylesheet outputs: CSS, LESS, Sass.
===== 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}.
~~Outcome: **Stylesheet variable definition is sufficient.**~~ In the Vue.js WMDE <> WMF task force we've agreed on JSON format
===== 2.4 Naming rules
See section in [[ https://www.mediawiki.org/wiki/Manual:Coding_conventions/CSS#Variable_naming | CSS coding guidelines on variable naming ]].
**Proposal**: `property-object-or-application[--modifier]`
=== 3. Presentation
===== 3.1 Design tokens visualization
How to simplify design, handover and QAing of tokens?
**Proposal**: 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.
{F34671777 width=25%}
(WikimediaUI Base tokens usage currently)
**Proposal**: 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
https://wmde.github.io/wikit/?path=/story/documentation-how-to-create-reusable-components-designing-components--page#2-using-design-tokens
==== Decision
At the October 2021 Design Systems Taskforce Summit it was [[ https://www.mediawiki.org/wiki/Design_Systems_Team/WMDE-WMF_task_force_decisions?useskinversion=2&vectorstickyheader=1 | 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.