Design and define design tokens
Design tokens are the smallest pieces of our design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for user-interface development.
Project Overview & Background
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
- 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.
|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||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||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||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||Done|
|Enable and document use of Codex design tokens within MediaWiki T325237||December 2022||February 2023||Done|
|Replace mediawiki.ui variables with mediawiki.skin.variables||March 2023||TBD||In progress|
|Provide Codex tokens a single source of truth including WikimediaUI Base T318016||TBD||TBD||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||Done|
- Codex design tokens* in MediaWiki core are enabled as of v1.41.0 via
- Codex design tokens are now available for use in MediaWiki as Less variables - Codex#Using Codex design tokens
- 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
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