1 of 21

Wikidata/Wikibase Design System�Why devs and designers love it

2 of 21

Vision

Optimise design and engineering processes and achieve overall consistency in the Wikidata/Wikibase platforms by replacing the current Front End with modular, reusable Vue components that are based on a single visual source of truth.

3 of 21

Why a system

Consistency = better user experience
Consolidate conflicting resources into a single source of truth for design
Base component implementation in a set of predefined, centralized and traceable design decisions
Improve design >< development communication and handover
Ensure component reusability

Using a Design System as a foundation for component development allows us to...

4 of 21

Design tokens

A systemic approach requires setting in advance the design direction that will guide component implementation.

Design principles are encoded in agnostic (JSON) design tokens: property/value pairs used to style components.

Design tokens are atoms that store the visual foundations of our design system. They exhaustively codify colors, spacing, typographic styles, and even transitions in an agnostic and scalable way. The whole purpose of using tokens is to replace concrete values or single-use variables at a component level. They prevent deviations from the system’s visual and interactive properties, and make style modifications possible at scale and from a single source of truth.

In the context of the Wikidata design system (WiKit), tokens are stored using JSON, and converted into actionable CSS variables that can be used to style components (via Style dictionary). Tokens are structured following three levels of granularity that reflect the chain of systematic decisions made: from high-level visual styles to specific component properties: They act as a source of truth for both implementation and design.

5 of 21

Design tokens

The Wikimedia Design Style Guide is our design source of truth. To ensure alignment, we base our global tokens on wikimedia-ui-base variables.

https://wmde.github.io/wikit/?path=/story/design-tokens-colors--page

https://github.com/wikimedia/wikimedia-ui-base/blob/.../wikimedia-ui-base.less

6 of 21

Components

To achieve consistency, the design of components must be solely based on the consolidated design principles: tokens are used as a common language during handover.

👉🏻 Check out component specs in Figma

7 of 21

Why we love tokens

8 of 21

Bridging the gap between development and design

Avoid using specific values and single use variables (threat to consistency)
Embed traceable design decisions directly in the component implementation
Share a common language between developers >< designers (specs)
Outsource and centralize design changes
Apply visual modifications without altering the component implementation

9 of 21

Accessible inventory

Along with the design system comes a way to showcase what it contains (in Storybook)

Status quo of the system is always accessible to anyone and everyone - without technological hurdles�
It’s in the tokens or it does not exist

No more guess-inspecting design files

10 of 21

Tokens influence each other

De-duplicates “magic” values�
Profound changes can be done from a central spot, propagate down

“with great power comes great responsibility”
encourages/allows designers to verify the consequences are actually intended before employing engineers

Effect of token changes, somewhere in the tree, on “tree leaves” is easily previewable

11 of 21

.button {

color: #000;

}

// wikimedia-ui-base

$wmf-wmui-color-base10: #202122;

// global

$color.base.10: $wmf-wmui-color-base10;

// alias

$font.color.base.value: $color.base.10;

// component-level token

$wikit-Button-color: $font.color.base;

.button {

color: $wikit-Button-color;

}

before

after

12 of 21

// wikimedia-ui-base

$wmf-wmui-color-base10: #2021223;

// global

$color.base.10: $wmf-wmui-color-base10;

// alias

$font.color.base.value: $color.base.10;

// component-level token

$wikit-Button-color: $font.color.base;

.button {

color: $wikit-Button-color;

}

https://twitter.com/sarah_federman/...

13 of 21

Tokens self-document

They communicate intent

No more “it’s not this blue, it’s that blue” - prevents guess work in case of values which look similar�

They communicate relationships

Tokens leading back to a shared base are conceptional peers

14 of 21

.input {

color: #000;

}

.button {

color: #000;

}

// ...

// component-level token

$wikit-Input-color: $font.color.somethingelse;

$wikit-Button-color: $font.color.base;

.input {

color: $wikit-Input-color;

}

.button {

color: $wikit-Button-color;

}

before

after

15 of 21

Explanations are part of the deliverable

Dedicated "comment" fields in the tokens files�
Everything is in version control, descriptive commit messages allow for archeology�
Can communicate TODOs, external constraints (for reevaluation) to our future self

16 of 21

Decoupling design from technology

Tokens are packaged separately and are compiled to different formats - CSS, Less, SCSS, etc.
They can be used in front ends before components exist in the Design System
This creates a level of agnosticism which enables UX Designers to apply Design System principles without depending on engineering

Mobile Apps
Front ends that don’t use the same technology as the Design System

By providing tokens separately from components we don’t observe any downsides, only benefits

Monorepo orchestrated by lerna
Tokens and components versions are always in sync

17 of 21

How did we

make this happen?

18 of 21

Tooling

Style-dictionary�

Enables participation by all roles (no “dev knowledge” required)
Creates technology agnosticism (i.e. “variables” in more than on frontend software format)

Everything in version control

Everything pushed to Github - all roles are empowered