Design Systems

Piping Design Tokens from Figma

Managing design tokens in Figma and synchronizing with a Git repository

The Retrospective

After spending the last five years or so working intimately with enterprise design systems, I thought it would be a good time to go back in time and start a new journey in a dedicated role with some of the knowledge and pain points I’ve experienced along the way.

In my last role, the internal teams split away from a Foundation CSS framework in favor of a Material-UI themed, CSS-in-JS approach. We were under the umbrella of Digital Transformation and Customer Experience creating React CRM applications for a series of callcenters.

We were able to quickly adopt this system using a custom dark and light theme to skin the components, create reusable UI components and rapidly evolve to a mature design system used by dozens of teams.

Fast-forward three years, I was still maintaining a reusable JS theme and some enterprise-wide navigation components based on Material-UI, which was working flawlessly for internal teams — little to no maintenance, only the major breaking change ever year or so…

Eventually, we were tasked with integrating UI with our externally facing website which was still using SCSS and Foundation with their own brand colors, SCSS themes, and business logic components they had built over the course of the last few years as well.

Without a major rewrite, collaboration between the teams and investment into resources to achieve this goal, this just was not going to be possible.

New Terrain

I accepted a new role as a Design Systems hybrid, tasked with designing and documenting the future state design system for a healthcare SaaS product with about 50 internal teams and over 160 external teams using our platform and services.

The company as a whole is in Angular, Angularjs and is migrating to React while still using a several versions of Bootstrap.

Goals

Now in a role dedicated to shipping this system, I had some technology goals specific to design tokens to ensure we didn’t dig ourselves into a hole:

• Use design tokens to future-proof technology decisions
• Manage tokens in Figma, so a designer can change a token value without needing development
• Use a transformer to translate design tokens into scss, css varibles, or js modules with Style Dictionary
• Document tokens, usage guidelines, accessibility and technical specifications side-by-side in Zeroheight

Figma Tokens

Basing an enterprise-wide design system on a plugin is always a gamble, but after some heavy research and proof-of-concept work, Figma Tokens really met my needs with an escape hatch — even if this plugin became unsupported at some point, I can still manually edit the tokens in Git.

The new system’s tokens were created with Figma tokens and also published as a library in Figma. This file serves as the the design system’s source of truth which is leveraged by other designers.

Within the plugin we can document base tokens and add semantic/alias tokens as the system scales for all of our core styles:

• color
• typography
• effect / depth
• motion
• shape
• spacing
• breakpoints

Style Dictionary

Design tokens are formatted in a JSON structure, which is a raw format. We still need to massage this structure in order to be consumable by the downstream applications. We’re leveraging an Amazon tool called Style Dictionary to transform the tokens into the format we need.

The format that Figma Tokens exports is not readily usable by Style Dictionary, we are using a utility written by Jan Six called token-transformer which modifies the JSON structure to a format that can be picked up by Style Dictionary.

Now that we have a working JSON structure, Style Dictionary has a ton of configuration options to meet pretty much anything you throw at it. I did write a custom transformer for box-shadows to ensure we had the correct string format for both ES6 variables and css/scss variables.

Git Actions

Figma Tokens can link directly to your GitHub repo, and you can create pull requests without ever having to leave Figma. We have a set of actions on the repo that kickoff a few steps every time you push to master:

name: CI
on: [push] 
jobs:  
  build:    
    runs-on: ubuntu-latest
     
    steps:      
      - uses: actions/checkout@v2      
      - name: Setup Node.js environment        
        uses: actions/setup-node@v2.4.0  
    
      # Clean Workspace      
      - run: rm -rf dist && rm -rf src/tokens  
    
      # Install dependencies      
      - run: npm install  
    
      # Transform tokens into SD readable tokens      
      - run: npx token-transformer src/tokens.json           src/tokens/core.json
      # Run Style Dictionary Build      
      - run: node build.js      
      # Add files that were created during a run, e.g. created files               from style dictionary or token-transformer.      
      - uses: stefanzweifel/git-auto-commit-action@v4        
      with: 
        commit_message: Update Tokens

We can also add another step to this workflow to increment the package.json version number and deploy to npm, we’re still at an early stage with this technology so will be looking to add that in the future. I’m still manually building npm packages for the time being.

Leveraging Tokens

Once Style Dictionary creates the tokens, we are deploying to npm as a package which downstream teams can install and use in their applications. I’m maintaining a theme for Material-UI, Tailwind and theming Bootstrap using the design tokens to complete the proof-of-technology.

Essentially, this proves this solution as a scalable way to abstract the design language away from future technology decisions and make us nimble enough to not have to do a rewrite in the event the direction changes.

As we scale the design system and move into a modern framework, or create bespoke components, this gives the enterprise the power to not get stuck rewriting the design and accessibility decisions at its foundation.