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 new repository (includes sample tokens that sync automatically)
2. Make a change in Figma
3. Push it back to GitHub

Step 1: Create a New Repository

1. Open GitFig in Figma
2. Click "Create New" tab
3. Select your Owner from the dropdown (your GitHub username or an organization)
4. Enter a Repository Name (e.g., design-tokens)
5. Click "Create"

GitFig creates a new repository with a sample-tokens.json file that includes example colors, spacing, and border radius tokens in W3C format. The file is automatically mapped to Variables and pulled—your Figma file now has Variables ready to use.

Using an existing repository?

Select the "Connect Existing" tab instead. Browse your repository's file tree, hover over a JSON file, and click "+ Add Target" to map it to Variables or Styles. Then click Pull to sync. See File Mappings for details.

---

Optional: Create Your Own Token File

If you want to practice creating token files manually, add a file like tokens/colors.json to any repository:

{
  "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"
    }
  }
}

Then connect that repository using the "Connect Existing" tab and configure a file mapping.

---

Step 2: Verify Variables in Figma

After creating a new repository, GitFig automatically pulls the sample tokens:

1. Open the Variables panel in Figma (right sidebar → Variables icon)
2. You should see a new collection with colors, spacing, and border radius values

Congratulations! Your tokens are synced from GitHub to Figma.

Step 3: 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, wait a few seconds - the change appears in Unstaged Changes
4. Click "Stage" (or "Stage All") to move it to Staged Changes
5. Enter a commit message: Change primary color to orange
6. (Optional) Add an extended description for more context
7. Click "Create Commit"
8. Click "Push 1 Commit" to push to GitHub

Step 4: Verify on GitHub

Open your repository on GitHub and check sample-tokens.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:

Goal	Guide
Learn token formats in depth	Token Formats
Set up branches for themes	Multi-Brand Themes Tutorial
Create PRs from Figma	Branch Workflows
Team collaboration tips	Team Collaboration Tutorial

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