Table of contents
When working on a design system, getting teams to communicate is non-negotiable. Everyone must be aware of what’s going on for the system to function effectively. This coordination keeps all elements of the design system consistent across all screens and working together smoothly.
Design and development work can be extra challenging to align. The two teams often have different processes, needs, and documentation methods, making it difficult to stay synchronized. Some tasks are time-consuming and demand significant effort from both sides.
A token handoff is one of those tasks.
At the start of a design system project, developers copy many parameters, like colors and spacing, from a Figma file into the codebase. As the design system grows, developers have to continuously monitor changes made by the design team in Figma to manually configure tokens in the codebase. Yes, it’s painfully time-consuming and, even worse, prone to errors.
In a perfect world with sunshine and rainbows, designers would consistently communicate their changes to developers. However, in reality, this communication handoff can break down, creating discrepancies between the design and codebase… and ending in tears.
Automating token handoff is the solution, keeping design and development in sync.
Belka’s tear-free soluzione
“But Mattia, why do we need automation instead of just more regular check-ins?”
I hear you.
While regular check-ins are foundational to any successful design system, automating parts of the information exchange is better. Automation reduces manual work and human error, saving your team valuable time and the heartbreak of losing crucial information.
While some products can do this for you (with a price tag attached), you can actually automate the handoff without them. All you need is a few tools you probably already use. This solution doesn’t require any coding, just a Figma plugin and a GitHub integration.
Sounds cool, right? Read on to learn more. And if you want to practice token handoff with Belka’s approach, you can do it with the repository we set up for you.
Step 1: Set up the token and agree on the structure
The first step to a token handoff is… having tokens.
Tokens can be set up by either the design team or the developer team. If the design team is first to introduce tokens, they shouldn’t do it in a vacuum.
The token structure should follow a standard that both designers and developers agree on. This is crucial for two reasons:
- Developers receive something they understand
- Tokens can be easily transformed into CSS variables (or other format used in the codebase)
With this setup, designers can use a Figma plugin to generate a JSON file containing the token library. We recommend TokensBrücke, a fantastico plugin that does just that. They can run the plugin, download the JSON file, and then pass it to the developers. Or, a more advanced option is to link the plugin directly to GitHub, which automatically sends the file and creates a pull request (PR).
Whichever option you choose, you’ll need some collaboration between designers and developers.
Step 2: Translate tokens to integrate with the codebase
With your token library in a JSON file on GitHub, it’s time to convert it into a usable format for your codebase. Depending on how your codebase is structured, this could mean transforming the JSON into CSS or a Tailwind configuration file, for example.
To do this, we use a popular tool called Style Dictionary. Developed by Amazon, Style Dictionary helps convert design tokens from JSON files into various formats like CSS or JavaScript. It operates through a simple Node.js script that can be run via the command line.
Here’s a high-level overview of how Style Dictionary works:
- Reading and analyzing: the source JSON file is read and analyzed
- Transformation: the tokens are processed through several transformations, which might adjust aspects like token names
- Formatting: finally, the transformed tokens are formatted into a specific output form, such as CSS variables or JavaScript files
At this point, developers have everything they need to integrate tokens into their codebase.
Step 3: Review and approve the tokens
Once the transformation is done, developers get the last say. They’ll have a PR containing a JSON file packed with all the shiny new tokens, plus a file with those same tokens converted into their favorite format. As with any PR, their task here is to review the changes for tokens broken in transit.
If everything works just fine, the developer can approve the PR and integrate the new tokens into the codebase, keeping design and development in sync and working smoothly together.
Automation complete
Automating token handoff between design and development maintains consistency, reduces manual effort, and keeps your sanity in-check. Practice with our Figma file and repository and give our recommended tools a try for a smoother, error-free integration of design tokens.
∗ ∗ ∗
Want more insights?
- A design system to build design systems
- What’s the recipe for a successful handoff?
- How to make your life easier and your code cleaner by using composable components
Want a safe pair of hands to help with your own design system?
Check Design System Audit, our service to make sure your design system brings you results.
