Skip to main content

Pulling Tokens

Pulling fetches JSON token files from GitHub and creates or updates Figma Variables and Styles.

Time: 3 minutes Difficulty: Beginner

How Pull Works​

When you click Pull, GitFig:

  1. Fetches the latest JSON files from your current branch
  2. Parses tokens based on the detected format
  3. Creates new Variable Collections (if they don't exist)
  4. Creates or updates Variables with the token values
  5. Updates the sync status
GitHub                    GitFig                     Figma
───────                   ──────                     ─────
colors.json  ────────►   Parse JSON  ────────►   Variable Collection
                         Detect format             ├── primary: #0066FF
                         Map values                ├── secondary: #6B7280
                                                   └── background: #FFFFFF

Perform a Pull​

Step 1: Check for Updates​

Look at the Pull button. If there are new commits since your last sync, you'll see a badge:

Pull Badge

Step 2: Click Pull​

Click the Pull button to start syncing.

Pull Button

Step 3: Watch Progress​

GitFig shows progress as it processes each file:

Pull Progress

Step 4: Verify Results​

After pull completes:

  1. Open the Variables panel in Figma
  2. Check that collections were created
  3. Verify variable values match your JSON

What Gets Created​

Variables​

JSON TypeFigma Variable Type
Color ($type: "color")COLOR
Number/Dimension ($type: "number")FLOAT
String ($type: "string")STRING
Boolean ($type: "boolean")BOOLEAN

Collections​

Each mapped JSON file creates one Variable Collection, named after the file:

  • colors.json → Collection named "colors"
  • tokens/spacing.json → Collection named "spacing"

Nested Tokens​

Nested JSON structures become grouped variables:

{
  "brand": {
    "primary": { "$value": "#0066FF", "$type": "color" },
    "secondary": { "$value": "#6B7280", "$type": "color" }
  }
}

Creates:

  • brand/primary
  • brand/secondary

Pull Behavior​

First Pull (New Collection)​

On first pull, GitFig creates everything fresh:

  • New Variable Collection
  • New Variables for each token
  • Descriptions from $description fields

Subsequent Pulls (Update)​

On later pulls, GitFig updates existing elements:

ScenarioBehavior
Token value changedUpdate the Variable value
New token addedCreate new Variable
Token removedVariable remains (not deleted)
Token renamedCreates new Variable (old remains)
note

GitFig doesn't delete Variables that are removed from JSON. This prevents accidental data loss.

Change Detection​

Commits Behind Badge​

The badge on the Pull button shows how many commits are on GitHub since your last sync:

  • No badge - You're up to date
  • "3" - Three commits since last sync

Auto-Refresh​

GitFig checks for new commits every 30 seconds. You can also click Refresh to check manually.

Conflict Warnings​

If you have local changes in Figma that haven't been pushed, and GitHub also has new commits, you'll see a conflict warning:

Conflict Warning

Options:

  • Pull anyway - Overwrites local changes with GitHub values
  • Push first - Push your changes before pulling
  • View diff - See what changed on GitHub

Troubleshooting​

"No variables created"​

  • Check file mappings are configured
  • Verify JSON format has $value fields
  • Check browser console for parsing errors

Wrong variable types​

  • Ensure $type is specified in JSON
  • Without $type, GitFig guesses based on value

Variables not updating​

  • Make sure you're on the correct branch
  • Check that the JSON file actually changed
  • Try disconnecting and reconnecting

Pull is slow​

  • Large JSON files take longer to parse
  • Many variables take time to create
  • Network latency affects GitHub API calls

Next Steps​

After pulling tokens: