Design Systems Team/Projects/Design and define design tokens


Project Overview & Background[edit]

Design tokens represent systematic design decisions upon which the style and behavior of components and patterns are exclusively based. 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 a few years, architectural decisions on the use of centralized style(sheet) variable definitions (starting as WikimediaUI Base variables, now referred to as design tokens) have accumulated in a number of tasks and places in MediaWiki and Wikimedia resources.

Goals of design tokens[edit]

  • Consistent values in development
  • Set of predefined, centralized, limited and traceable design decisions
  • Single source of truth for design to development handover

A nice write-up on design tokens can be found at CSS-Tricks, featuring this summary from 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.


Project phases come from Wikimedia Foundation's Inclusive Product Development playbook.

Phase What? How?


Target Start Target Completion Status
Strategize Articulate “why” and “for whom?”

Assess team's capabilities to deliver.

Surface dependencies and risks.

Establish community engagement strategy.

Decide on design tokens architecture for Wikimedia Design System and its shared component library


July 2021 March 2022 Yes Done
Discover Better understand the needs and goals of target audience
Define Turn research, insights, etc. into an addressable and achievable scope of work with a concise problem statement. Resolve key questions for design of shared component library T287532

Resolve key questions for development of shared component library T286946

July 2021 March 2022 Yes Done
Develop Design and development of solutions and experiments from the DEFINE phase, in preparation for the DELIVER phase. Publish design tokens to Figma T295991 November 2021 November 2022 Yes Done
Deliver Deliver and test final code and/or interface. This could be either for delivering a smaller scaled test or final scaled experience to production. Publish the design-tokens package in NPM T322274 November 2022 November 2022 Yes Done
Enable and document use of Codex design tokens within MediaWiki T325237 December 2022 February 2023 Yes Done
Replace mediawiki.ui variables with March 2023 TBD In progress In progress
Provide Codex tokens a single source of truth including WikimediaUI Base T318016 TBD TBD N Not done
Own Monitor and refine based on positive and negative impacts resulting from the product/code delivered. Documentation for designing tokens T295605 November 2021 January 2023 Yes Done






  • Codex design-tokens patch released on NPM with version 0.4.0 and internally in MediaWiki's foreign resources registry (the latter only includes the LESS variables for now)
  • Project page created

How to Engage[edit]

We welcome and encourage your participation in this initiative. Here are some ways to engage:

  • Add this page to your watchlist
  • Add your questions, concerns, and ideas to the talk page
  • Subscribe to relevant Phabricator tasks, linked above
  • For Wikimedia Foundation staff: join the #talk-to-design-systems-team Slack channel