How to Sync Figma Variables with FigMayo Effortlessly

The Christmas break gave us a bit of breathing room to think about sharing the internal tools we have developed over the last year to complement FigMayo. We wanted to start the new year by addressing a hot potato - how to keep design tokens in sync between Figma and your codebase when (like most of us) you don't have access to Figma's enterprise APIs.

To solve this internally we have a simple GitHub action setup that automates away the steps of downloading variables from FigMayo, pushing them up to our app repositories, raising PR's for review and to trigger unit and visual regression tests.

When your variables are changing frequently, repeating this process becomes a pain for everyone. For less technical team members jumping into the codebase, pushing branches and raising PR's can be a headache. For us, it was a problem crying out for a bit of automation.

Like everything we do this approach is optimised for simplicity and low-friction. No massive engineering overhead to get setup and no complex CI to maintain. The workflow is safe and can be triggered with a single click in the GitHub UI and will inherit all the access controls and branch protection already setup in your code repos.

---

Prerequisites

You will need a FigMayo documentation site with your Figma variables published via our Figma Plugin which you can find here.

How it works

The workflow glues together a few straightforward steps:

1. It grabs a JSON representation of your Figma variables from the FigMayo API.

2. It saves the JSON to a path in your codebase

3. It uses git to establish if there are any changes to the JSON

4. If there are, it raises a PR using the gh CLI

It's worth noting that if your FigMayo documentation site has many libraries with published variables, we will merge this into a single JSON object which makes resolving aliased variables between libraries much easier.

Getting started

Set up is very straight forward. You can get going by dropping the following YAML file into your .github/workflows directory, setting up a couple of secrets on your repository and adjusting the file-path input to suit your project.

You can find complete instructions on getting setup with FigMayo and creating the required secrets on our listing on the GitHub Marketplace.

# .github/workflows/sync-figma-variables.yml

name: Sync Figma Variables with FigMayo
on:
  workflow_dispatch: # Manual trigger
jobs:
  sync-tokens:
    runs-on: ubuntu-latest
    steps:
        uses: figmayo/figma-variables@v1.0.2
        with:
          github-pat: ${{ secrets.GH_PAT }}
          figmayo-api-key: ${{ secrets.FIGMAYO_API_KEY }}
          file-path: "src/design-tokens.json" # <-- The target path for the JSON

Once the workflow is setup it can be triggered manually from the actions tab in your repository. Once the action completes a new PR will be available with a generated branch name and any changes to the JSON fill captured by the git diff.

Taking things further

In our internal implementation there is a few ongoing workflow steps to generate types and run code formatting which we stripped out to make the workflow more generalisable.

Its likely there are more steps you want to take - like converting the JSON into CSS variables or other platform specific representations. If you want to learn more about how to use Style Dictionary for this purpose I can recommend this article by James Ives.

To support ongoing workflow steps the GHA will yield the following useful outputs.

The .github/workflows/sync-figma-variables.yml test workflow in the project repo shows how you can access these outputs in any ongoing steps you might need to take.

name: Test Sync Figma Variables Action

on:
  workflow_dispatch: # Allows manual execution

jobs:
  sync-figma-variables:
    runs-on: ubuntu-latest
    outputs:
      # If you need to access step outputs in another job you must map them here
      changes: ${{ steps.test-sync.outputs.changes }}
      branch-name: ${{ steps.test-sync.outputs.branch-name }}
      pr-url: ${{ steps.test-sync.outputs.pr-url }}
    steps:
      - name: Test Sync Figma Variables
        id: test-sync
        uses: ./
        with:
          gh-pat: ${{ secrets.GH_PAT }}
          figmayo-api-key: ${{ secrets.FIGMAYO_API_KEY }}
          file-path: "test/figma-variables.json"

      - name: Debug GITHUB_ENV
        shell: bash
        # Within the same job you can access the GITHUB_ENV directly
        run: |
          echo "Changes: ${{ env.CHANGES }}"
          echo "Branch Name: ${{ env.BRANCH_NAME || 'No branch created' }}"
          echo "PR URL: ${{ env.PR_URL || 'No PR created' }}"

        # Or you can find them in the step outputs
      - name: Debug GITHUB_OUTPUT
        shell: bash
        run: |
          echo "Changes: ${{ steps.test-sync.outputs.changes }}"
          echo "Branch Name: ${{ steps.test-sync.outputs.branch-name || 'No branch created' }}"
          echo "PR URL: ${{ steps.test-sync.outputs.pr-url || 'No PR created' }}"

  test-outputs:
    runs-on: ubuntu-latest
    needs: sync-figma-variables
    steps:
        # Accessing the mapped outputs from the previous job
      - run: echo '${{ toJSON(needs.sync-figma-variables.outputs) }}'

Whats next

To make this process even easier for our customers, the next step is to deeply integrate variable deployment into our plugin so designers can kick off this process right from the Figma UI.

We’re also working on adding transformations to convert Figma variables into formats like CSS/SASS variables, WCAG-compliant design tokens, Tailwind themes, and platform-specific outputs, including Swift constants for iOS and XML resources for Android.

Join us on Slack