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 starter tokens and styles 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 and click Connect Repository
2. Check the Owner (your GitHub account is preselected; open it to pick an organization)
3. In Repository, type the name you want (e.g., design-tokens)
4. Choose Create "design-tokens" at the bottom of the list, keep Private
5. Click Create and connect

GitFig creates a new repository with four starter files in W3C format: tokens/primitives.json (color scales and spacing, one mode), tokens/semantic.json (a light/dark collection that aliases into Primitives), tokens/color-styles.json (three color styles), and tokens/text-styles.json (three Inter text styles). Each is mapped to its target (Semantic as All modes, the style files as Color styles and Text styles) and pulled, so your Figma file now has a Primitives and a Semantic collection plus six styles ready to use. The same files are published in the variable-modes example. On Figma's Starter plan only the first mode is created; the second is reported as skipped.

Using an existing repository?

Pick it from the Repository list (or type its name) and click Connect. Then, in Mapping, hover a JSON file (or Tab to it) and click Add target to map it to Variables or a style type. GitFig then prompts you to Pull; click Pull to import the file. 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 (pick it in the Repository field and click Connect) and add a mapping for the file.

---

Step 2: Verify Variables in Figma

After creating a new repository, GitFig automatically pulls the starter files:

1. Open the Variables panel in Figma (left navigation bar → Variables tab). See Figma's guide.
2. You should see two collections: Primitives (gray and blue scales, spacing) and Semantic with light and dark modes. Toggle the mode on Semantic and watch every aliased value switch.
3. Open the Local styles panel: three color styles (Brand-Primary, Brand-Primary-Hover, Overlay-Scrim) and three text styles (Heading-Large, Body, Caption).

Your tokens are now 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, open Primitives and click blue/500
2. Change the color to #FF6600 (orange)
3. In GitFig, the change appears in Changes within a few seconds, checked and ready to commit (uncheck anything you want to leave out)
4. In Commit, type Change primary color to orange (extra lines become the description)
5. Click Commit 1 change, or press Ctrl/Cmd+Enter
6. Under Ready to push, click Push 1 commit

Step 4: Verify on GitHub

Open your repository on GitHub and check tokens/primitives.json. blue.500 should now be #FF6600, and its $extensions block is untouched:

"500": {
  "$value": "#FF6600",
  "$type": "color",
  "$extensions": { "com.example.build": { "cssVariable": "--blue-500" } }
}

What's Next?

That is the whole loop: edit in Figma, commit, push. 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