== 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
=== Design & definition
===== 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.
===== Design tokens abstraction
{T266688}
=== Tech considerations
===== Repository or “where they live”
Currently in Wikimedia Foundation land, we've got them as separate library, WikimediaUI Base 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 and icons in different stylesheet outputs: CSS, LESS, Sass.
===== File source format
What file source format is most productive/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.**
===== Naming rules
See section in [[ https://www.mediawiki.org/wiki/Manual:Coding_conventions/CSS#Variable_naming | CSS coding guidelines on variable naming ]].
**Proposal**: `property-theme_or_application[--modifier]`
=== Presentation
===== 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)
===== 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.
**Proposal**: Monorepo with sub-package(s) tokens and icons in different stylesheet outputs: CSS, LESS, Sass.
---
===== Implementations elsewhere
https://wmde.github.io/wikit/?path=/story/documentation-how-to-create-reusable-components-designing-components--page#2-using-design-tokens