Skip to main content

Pulling Tokens

Pulling fetches JSON token files from GitHub and creates or updates Figma variables and styles. Variables mappings create or update a variable collection; Color, Text, and Effect Styles mappings create or update styles by name (a text style is skipped with a warning if its font is not available in the file).

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. Applies every file as one step in Figma's undo history
  4. Creates new variable collections (if they do not exist)
  5. Creates or updates variables and styles with the token values
  6. Rebases change detection and shows one summary
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 the header​

The Pull button turns blue when the branch has commits you have not pulled, with the count inside the button. The row under the header shows the latest commit message. Right after connecting, the row reads "Not pulled yet" until your first pull.

Step 2: Click Pull​

With no changes listed in Changes, Pull runs immediately.

If you have changes in Figma that are not committed, Pull asks first: "Pull will overwrite N changes in Figma." Choose Pull and overwrite or Cancel. Pending commits are not affected by a pull.

Step 3: Read the summary​

One toast reports the result, for example "Pulled 4 files: 2 created, 33 updated". If a file was skipped, a second toast names it.

Step 4: Undo if needed​

The summary toast offers Undo for a few seconds. It reverts the whole pull in one step and restores your change list, as long as you have not edited anything in Figma since. Figma's own Edit > Undo does the same, because a pull is a single undo step.

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 mapping's collection name (the file name by default):

  • 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 and brand/secondary.

Pull Behavior​

First pull​

On first pull, GitFig creates everything fresh: the collection, a variable per token, descriptions from $description.

Later pulls​

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

GitFig does not delete variables that are removed from JSON. This prevents accidental data loss.

Staying Current​

GitFig checks the branch every 30 seconds while the plugin is open. When new commits appear, the Pull button turns blue with the count and the Mapping file list refreshes. Hover Pull to see when it last checked.

Troubleshooting​

"No variables created"​

  • Check that a mapping exists for the file (the Mapping section lists them)
  • Verify the JSON has $value fields
  • Check the browser console for parsing errors

Wrong variable types​

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

Variables not updating​

  • Make sure you are 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: