Skip to main content

Quick Start

This guide walks you through syncing design tokens between Figma and GitHub in 5 minutes.

Time: 5 minutes Difficulty: Beginner Prerequisites: GitFig installed, GitHub authenticated

What We'll Do​

  1. Create a simple token file in GitHub
  2. Connect it to Figma
  3. Pull tokens to create Figma Variables
  4. Make a change and push it back

Step 1: Create a Token File​

First, create a JSON token file in your GitHub repository. You can use any repo you have write access to.

Create a file called tokens/colors.json:

{
  "colors": {
    "primary": {
      "$value": "#0066FF",
      "$type": "color",
      "$description": "Primary brand color"
    },
    "secondary": {
      "$value": "#6B7280",
      "$type": "color",
      "$description": "Secondary text color"
    },
    "background": {
      "$value": "#FFFFFF",
      "$type": "color"
    },
    "surface": {
      "$value": "#F3F4F6",
      "$type": "color"
    }
  }
}

Commit this file to your main branch.

Step 2: Connect to Repository​

  1. Open GitFig in Figma
  2. Make sure Design Sync mode is selected (default)
  3. Enter your repository in the format owner/repo (e.g., myname/design-tokens)
  4. Click "Connect"

Connect Repository

Step 3: Configure File Mapping​

  1. Click "Configure" next to "Sync Mappings"
  2. Browse to your tokens/colors.json file
  3. Click on it to select
  4. Choose "Variables" as the target type
  5. Click "Add Mapping"
  6. Click "Save Mappings"

Configure Mapping

Step 4: Pull Tokens​

  1. Click the "Pull" button
  2. Watch as GitFig creates Variables in Figma

Pull in Progress

  1. Open Variables panel in Figma (right sidebar → Variables icon)
  2. You should see a new collection with your colors:

Variables Created

🎉 Congratulations! Your tokens are now synced from GitHub to Figma.

Step 5: Make a Change​

Let's test the round-trip by changing a color in Figma:

  1. In the Variables panel, click on primary
  2. Change the color to #FF6600 (orange)
  3. In GitFig, click "Push"
  4. Enter a commit message: "Change primary color to orange"
  5. Click "Push to GitHub"

Push Changes

Step 6: Verify on GitHub​

Open your repository on GitHub and check tokens/colors.json. The primary color should now be #FF6600:

"primary": {
  "$value": "#FF6600",
  "$type": "color",
  "$description": "Primary brand color"
}

What's Next?​

You've completed the basic workflow! Here are some next steps:

GoalGuide
Learn token formats in depthToken Formats
Set up branches for themesMulti-Brand Themes Tutorial
Create PRs from FigmaBranch Workflows
Sync Figma Make filesMake Bridge Setup

Common Issues​

"No variables created"​

  • Check that your JSON follows the W3C Design Tokens format
  • Ensure $value and $type are present for each token
  • Check the browser console for errors (Figma → Plugins → Development → Open Console)

"Repository not found"​

  • Verify the repo format is owner/repo (not a full URL)
  • Check you have at least read access to the repository
  • Try signing out and back in to refresh your token