How to sync design tokens in your GitHub monorepo

In this article you’ll learn how to generate CSS Custom Properties from design tokens in Specify and sync them to your GitHub monorepo.

Head over this article to learn more about how to sync design tokens from Figma to Specify.

Prerequisites

Before anything else, please make sure you have:

1. created a Specify account

2. collected design data from Figma to a Specify repository

The Workflow

Specify is a design token engine which offers an API. This means you can request tokens from Specify while transforming them or their organizational structure along the way.

Let’s say you have several products to support and each of them has a dedicated:

• Figma library

• Specify repository

• Folder in your GitHub monorepo containing a Specify configuration file which targets a specific Specify repository (e.g., .specifyrc-a.json targets the “Product A” repository).

We will generate the following code:

🗂 product-a
└── .specifyrc.json
└── 🗂 styles
    └── colors.css
    └── spacing.css
    └── text-styles.css
🗂 product-b
└── .specifyrc.json
└── 🗂 styles
    └── colors.css
    └── spacing.css
    └── text-styles.css
🗂 product-c
└── .specifyrc.json
└── 🗂 styles
    └── colors.css
    └── spacing.css
    └── text-styles.css

As you can see we’re essentially doing the same thing 3 times. We’ll focus on how to sync design tokens as CSS Custom Properties in a single folder. Once we have something working, we’ll replicate our working flow for the remaining products (B and C).

Here’s what we will do for each product:

1. Use the Specify CLI to extract tokens locally and iterate in our local git directory

2. Set a working configuration file in GitHub to get automated Pull Requests

Syncing design tokens for one product

Using the CLI

The Specify CLI helps you get design tokens and assets from Specify right from the terminal or even in a CI/CD pipeline.

Installation

First of all, let's install the Specify CLI: yarn global add @specifyapp/cli.

Once the Specify CLI is installed, run the specify command. You should see the following menu:

Configuring Specify

The Specify Design Token Engine is powerful but you need to ask him what to generate for you so you get design tokens and assets that match your needs.

In our case we want our colors, spacing and text styles to be pulled and generated as CSS Custom Properties.

1. Create a .specifyrc.json Specify configuration inside our project folder

2. Paste the following configuration in our file

3. Set the Specify repository we're pulling design data from. In our case we're pulling design data from the all-design-data repository created in the @acme-inc organization.

4. Generate a new personal access token and set it in the personalAccessToken property

This configuration is now ready to be executed.

Let's run it by executing: specify pull.

Syncing design tokens in GitHub

The Specify GitHub app helps you distribute your design tokens and assets from your Specify repository to your GitHub repositories. Every change detected in your Specify repository creates a Pull Request in your GitHub repositories.

1. Head over to the Specify repository you want to pull your design tokens from

2. Go to your repository Destinations page

3. Click on “Create pipeline”

4. Select “GitHub Repository”

5. Select your GitHub account and your GitHub repository

6. Set the path of your configuration file (e.g., product-a/.specifyrc.json)

7. Create the Pull Request

8. Replace the content of the .specifyrc.json file in the PR by the content of the .specifyrc.json file we used with the CLI.

9. Set your repository in the repository property

10. Remove the personalAccessToken property which is not needed on GitHub.

11. Merge the Pull Request containing your Specify config file

12. Specify will create a new PR containing your generated CSS files

13. Merge the Pull Request

Replicating our working flow for products B and C

Now we have something working for Product A let’s do the same thing for product B and C.

We’ll end up with the following structure in GitHub:

Let's sum things up

We've learned how to synchronize design tokens from several products to our GitHub monorepo.

We've used the CSS Custom Properties Configuration Template in two ways:

• with the Specify CLI to pull design tokens in our local git directories

• with the Specify GitHub app to pull design tokens in our GitHub monorepo

Don't see the configuration template you're looking for? Feel free to request a template ↗.