Sync Tokens Studio to GitHub

Why This Matters for Your Design System

Last year I watched a design system lead spend 45 minutes tracing a color bug. The value in Figma was right. The value in code was wrong. Nobody could tell when it drifted or who changed it, because the “sync process” was a Slack message that said “updated tokens, can you pull?”

Tokens Studio connected to GitHub ends that entire category of problem. You update a token in Figma, push it to a branch, and it lands in code with a full history. Who changed it, when, and why. If something breaks, you roll it back in one click. This workflow sets up that connection in about 15 minutes.

---

Step 1: Create a GitHub Repository

If you do not already have a repository for your tokens, create one now.

1. Go to github.com/new
2. Name it something clear, like design-tokens or my-company-tokens
3. Set it to Private (your design decisions do not need to be public)
4. Check “Add a README file” (this is required because Tokens Studio cannot sync to an empty repository)
5. Click “Create repository”

Save the repository URL. You will need the owner/repo format (for example, yourname/design-tokens).

Why this step matters: The repository is where your token data lives as structured JSON. It becomes the single source of truth that both designers and engineers reference. Even if you never look at GitHub again after this setup, your tokens are being version-controlled, backed up, and made available to the engineering workflow.

---

Step 2: Generate a Personal Access Token

GitHub needs to verify that the Tokens Studio plugin has permission to read and write to your repository. You do this by creating a Personal Access Token (PAT), which is essentially a password that grants specific access.

1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
2. Click “Generate new token” and choose “Fine-grained token” (recommended for better security)
3. Give it a descriptive name, like tokens-studio-sync
4. Set an expiration (90 days is a good balance between security and convenience)
5. Under “Repository access,” select “Only select repositories” and choose your token repository
6. Under “Repository permissions,” set “Contents” to “Read and Write”
7. Click “Generate token”
8. Copy the token immediately and save it somewhere safe. You will not be able to see it again.

Why this step matters: The fine-grained token limits access to just the repository you specify. This is a security best practice. If the token is ever compromised, the exposure is limited to your token files, not your entire GitHub account.

---

Step 3: Connect Tokens Studio to GitHub

Now open Figma and launch the Tokens Studio plugin.

1. Go to the Settings tab in the plugin
2. Under “Sync providers,” click Add new
3. Select GitHub
4. Fill in the form:
   • Name: A label for this connection (e.g., “Design System Tokens”)
   • Personal Access Token: Paste the token you generated in Step 2
   • Repository: Enter it in owner/repo format (e.g., yourname/design-tokens)
   • Branch: Enter main (or whatever your default branch is called)
   • File Path: Enter tokens (this creates a folder called tokens in your repository)
5. Click Save

The plugin will compare your local tokens with what is in the repository. Since the repository is new, it will ask you to push your tokens.

Why this step matters: The file path setting is important. Choosing “folder” mode (just a folder name without a .json extension) stores each token set as a separate JSON file. This is much better for engineering workflows because tools like Style Dictionary can process individual files. If you use a single file path like tokens.json, everything gets merged into one file, which is harder to work with.

---

Step 4: Push and Pull Tokens

With the connection established, you now have two-way sync between Figma and GitHub.

Pushing (Figma to GitHub): When you make changes to your tokens in Figma (adding a new color, updating a spacing value, renaming a token), the plugin shows a push indicator. Click it, add a brief description of what you changed (like “Updated primary blue to match brand refresh”), and push.

Your changes are now in GitHub as a new commit. Engineers can see exactly what changed in the commit diff.

Pulling (GitHub to Figma): If someone updates the token JSON files directly in GitHub (an engineer fixing a value, for example), the plugin shows a pull indicator. Click it to bring those changes into your Figma file.

Tokens Studio Sync Status:
  ↑ Push: You have local changes to send to GitHub
  ↓ Pull: There are remote changes to bring into Figma
  ✓ Synced: Everything is up to date

Why this step matters: The push/pull model mirrors how engineers use Git. You are not replacing their workflow. You are joining it. When you push a token change, it shows up in the same pull request interface that engineers use to review code changes. This makes design decisions visible and reviewable by the whole team.

---

Step 5: Set Up a Branching Workflow (Optional but Powerful)

For teams that want an extra layer of review before token changes go live, Tokens Studio supports creating branches directly from the plugin.

1. In the plugin, click the branch dropdown (next to the push/pull buttons)
2. Create a new branch (e.g., update-brand-colors)
3. Make your token changes
4. Push to the new branch
5. Go to GitHub and create a Pull Request from your branch to main
6. Ask your team to review the changes
7. Merge the Pull Request when approved

This adds a review step between “designer updates a token” and “the change goes live.” It is particularly useful for large-scale changes like a brand refresh or a new theme.

Why this step matters: Branching prevents accidental changes from immediately affecting production. If you update 50 tokens at once, the branch gives your team a chance to review everything together before it merges. This is the same safety net that engineering teams rely on for code changes.

---

What You Get

• Version history for design decisions. Every token change is recorded with a timestamp, author, and description.
• Two-way sync. Designers update tokens in Figma, engineers can update them in code. Both sides stay current.
• Structured JSON files in GitHub. Your tokens are stored as clean, machine-readable JSON that any build tool can consume.
• A foundation for automation. Once tokens are in GitHub, you can add GitHub Actions to automatically build and publish them on every change.

---

Common Pitfalls

• Empty repository. Tokens Studio cannot sync to a repository without at least one file. Always initialize with a README.
• Expired access token. If sync stops working after a few months, your PAT may have expired. Generate a new one and update the credentials in the plugin settings.
• Push/pull indicator stuck. Occasionally the sync indicator persists after a successful push or pull. Try pushing or pulling one more time. This is a known minor issue in the plugin.
• Single file vs. folder. If you entered a path ending in .json (like tokens.json), your tokens are stored as a single file. For better engineering compatibility, use a folder path (like tokens).

---

Exercise

Push your first token change through the sync

15 min

1. Make one token change in Figma and push it

   In Figma, open the Tokens Studio plugin. Pick a low-risk token (a spacing step you rarely use, or a color you can revert). Change the value. Commit the change inside the plugin with a message like test: bump spacing.xs to verify sync.

   • The plugin’s push indicator clears once the commit lands
   • The commit message names the token that changed, not a vague “update tokens”
   • No other tokens changed in the same commit

2. Verify the commit in GitHub and pull a counter-change

   Open the repository on GitHub. Find the commit you just pushed. Open the JSON file and confirm the new value is present. Then edit the same file directly in GitHub (revert the value), commit on the main branch, and in Figma click the pull indicator. The original value should reappear.

   • The GitHub commit shows a clean diff with only the token you changed
   • Tokens Studio flags the remote change and offers to pull
   • After pull, Figma shows the reverted value without any manual edit
   • You now trust that both directions work, not just the one you tested first