Mística is a multi-brand design system, which means that every time we need to add or change a design token in the system, we need to multiply the change by the number of brands we support, reviewing these changes can be challenging and time-consuming.
The process always starts in the repository where we have allocated the design tokens, each brand has its own skin, a skin is a JSON file where we store all the design decisions for that brand, then we then pull those tokens with Tokens Studio to Figma and development have this files as the source of truth.
Fig. 1 - The journey of a design token in Mística.
To change a token value we need to go to the skin JSON file a create a PR to the production branch of the mistica-design repository, where tokens can be fetched to update in the Figma libraries and development repositories.
We are also involved in automating the process of fetching the tokens from the development repositories.
Problem statement
Each time we needed to review token changes it was done over a plain JSON, in order to see the changes visually we needed to:
Go to Figma
Change the branch that Tokens Studio is pointing
Create a branch in the libraries of each brand
Fetch the changes
And it would only work if the JSON file was valid. The tokens have to be written in a specific format so Tokens Studio can extract the value correctly. When you're reviewing changes in a JSON file over 1800 lines long, it's easy to miss a token with the wrong format.
The questions we asked ourselves were:
How can we make the review process more reliable and help designers to detect format errors before submitting the PR?
How can we improve the review process by giving a visual example of the changes that is generated automatically?
Solution
We decided to create a tool that would:
Fetch the JSON files of a specific branch of the repository.
Display all the available tokens in different tables depending on the token type and add a detail of the token value in each brand.
Display format errors in a user-friendly way so it's easy to understand what changes need to be made in the JSON.
Add automatically a comment in the PR pointing to the token list in the branch that we're merging into production.
If you're interested in a more detailed explanation of how we built this tool I wrote a blog post about it.