Skip to main content

Pushing Tokens

GitFig tracks what you change in Figma, lets you choose what to commit, and pushes the result to GitHub. Changes are detected automatically; you check the ones to include, write a message, commit, and push.

Time: 5 minutes Difficulty: Beginner

The Workflow​

Edit in Figma  →  Changes (checked = in the next commit)  →  Commit  →  Ready to push  →  Push to GitHub

The linked panel is ordered by what you do most often:

SectionPurpose
ChangesEverything that differs from the last sync, each with a checkbox
CommitThe message and the Commit button; below it, commits that are ready to push
MappingWhich repository files sync to which Figma targets (collapses once set up)

Step 1: Make Changes in Figma​

Edit your variables or styles in Figma:

  • Change a color value
  • Add a new variable
  • Update a description
  • Delete a variable

GitFig detects changes within a few seconds and lists them in Changes. Revert an edit in Figma and its row disappears again.

Reading a row​

GlyphMeaning
+ (green)Added
~ (yellow)Modified
- (red)Removed

Each row shows the item (for variables, the collection in gray, then the variable name), its type (Variable, Color style, Text style, Effect style), and the mode when a collection has more than one. Hover a row to see the old and new value.

Step 2: Choose What to Commit​

Every change starts checked. Uncheck anything you want to leave out of the next commit; it stays in the list for later. Once you have unchecked something, new changes arrive unchecked so they cannot slip into a commit you are composing. Select all returns to the default; Clear unchecks everything.

Checked rows are exactly what the commit contains. Unchecked changes are not written to the repository, and they remain listed after you push.

Step 3: Commit​

Type a message in the Commit box and click Commit N changes (or press Ctrl/Cmd+Enter). The button stays gray until there is a message and at least one checked change.

  • The first line is the commit subject (50 characters or less recommended)
  • Additional lines become the description: why the change was made, related decisions, links to specs or tickets
note

Committing does not push to GitHub yet. Commits are stored with your connection and can be pushed later, from this or another machine.

Step 4: Push​

Commits appear in Ready to push under the Commit box, with Push N commits always visible. Expand a commit to see its message and items; use the trash icon to discard one (its changes return to the list).

Click Push N commits. GitFig squashes pending commits into one commit on your current branch, using the first commit's message.

What happens during push​

  1. GitFig exports your current variables and styles, one file per mapping, with your unchecked changes reverted
  2. Merges each file against the version in your repository, so $extensions and other repo-owned metadata survive untouched
  3. Creates a single commit on GitHub containing all mapped files
  4. Rebases change detection, keeping your unchecked changes listed

Push Options​

Direct push (default)​

Commits directly to your current branch. Best for personal projects, quick iterations, and when you have push access.

Create a pull request​

On a feature branch, a Create pull request button appears below the Commit section. Push first, then create the PR with a title and description. Best for team projects that require review and for protected branches.

If GitHub Has Commits You Have Not Pulled​

Pushing shows a confirmation in place of the button: "The branch has N new commits you have not pulled. Pushing may overwrite them." Choose Pull first (recommended), Push anyway, or Cancel.

What Gets Exported​

Variables to JSON​

Variables are exported in W3C Design Tokens format:

{
  "primary": {
    "$value": "#FF6600",
    "$type": "color",
    "$description": "Primary brand color"
  },
  "spacing-sm": {
    "$value": 8,
    "$type": "number"
  }
}

Variable types​

Figma typeJSON $type
COLOR"color"
FLOAT"number"
STRING"string"
BOOLEAN"boolean"

Nested variables​

Variable names with / become nested JSON:

Variable nameJSON structure
brand/primary{"brand": {"primary": {...}}}
spacing/sm{"spacing": {"sm": {...}}}

Cross-Device Support​

Commits are stored with your connection, so you can create commits on one device, push them from another, and see pending commits on any device with access.

Troubleshooting​

Changes not appearing​

  • Wait a few seconds; detection runs every 3 seconds
  • Check that you have at least one mapping (the Changes section says so when you do not)
  • Try closing and reopening the plugin

"Push failed: permission denied"​

  • Check you have write access to the repository
  • The branch may be protected; create a PR instead
  • Your token may have expired; sign out and back in

Best Practices​

Write clear commit messages​

GoodBad
"Update button colors for dark mode""changes"
"Add new spacing tokens (4, 8, 12, 16)""update tokens"
"Fix contrast issue on secondary color""fix"

Use the description for context​

Add a description when the change needs explanation beyond the subject, when you want to link to specs or tickets, or when several related changes are bundled.

Commit often​

Small, frequent commits are easier to review than large, infrequent ones.

Pull before push​

Pull the latest changes before pushing to avoid overwriting work.

Next Steps​