Contributing Design Tokens
Contributions are welcome across the system, but token updates need special care, as they are the foundation of our design system.
- The single source of truth for tokens is the design-tokens repository.
- On the design side, tokens live in our Figma library as Variables and Styles.
To keep design and code aligned, we use Tokens Studio, a third-party Figma plugin that lets us edit tokens and push changes to the repository through an automated PR flow.
Before you start
- Review the Design Tokens Overview to understand structure and naming.
- Search existing tokens to avoid duplicates.
- Coordinate foundational changes with the committee before updating anything.
Setting up Tokens Studio
When you open the plugin, you'll see that the tokens are organized into several sets. Some of these sets are related.
To make sure your changes apply correctly, you have to select the theme you're working on and the reference sets it depends on before editing or exporting tokens.
Themes can be referenced to each other
- With nothing selected in the canvas, open Tokens Studio in the MDS Tokens 2.0 file.
- Create a branch for your contribution.
- Select the theme you want to edit (e.g., B2B Light, B2B Dark, GX Light, GX Dark).
-
Select the reference sets that the theme depends on (see table below).
These sets must stay selected when editing or exporting.
|
Theme |
Reference sets |
|---|---|
|
Foundations |
- |
|
B2B Light |
Foundations, Palette Light, Legacy Light |
|
B2B Dark |
Foundations, Palette Dark, Legacy Dark |
|
GX Light |
Foundations, Palette Light, Legacy Light |
|
GX Dark |
Foundations, Palette Dark, Legacy Dark |
Ensure all relevant themes are selected, both in the sidebar and Theme dropdown
Editing or adding tokens
Whether you are editing or adding a token, the workflow is the same.
Editing:
- Right-click the token.
- Choose Edit token.
- Update its name, value, or description and save.
Adding:
- Click Add a new token (+) in the correct group.
- Select reference token from Palette Light, Palette Dark, or Foundations.
- Name it according to naming conventions.
Exporting changes to Figma
In Tokens Studio, export changes one theme at a time:
- Go to Styles and Variables → Export Styles & Variables to Figma.
- Select relevant update areas (variable types, styles).
- Select the main theme and relevant reference sets to ensure changes are applied correctly.
- Confirm your updates appear correctly in the Variables and/or Styles panels.
- Repeat the process for the other themes, always selecting the main theme + reference sets.
For better results, export changes theme by theme (B2B Light, B2B Dark, GX Light, GX Dark)
To delete a token, follow the same process and enable the Remove styles and variables without connection to a token option.
Pushing changes to GitHub
When everything looks correct in Figma:
- Click Push to GitHub in Tokens Studio.
- Add a clear commit message describing your change.
- Click Push Changes.
- Contact engineering to review, merge, and deploy the update.
Useful links
- Mews Design Tokens Overview
- Design Tokens Repository
- Tokens Studio setup in Figma
- Tokens Studio official documentation