Skip to main content

Pushing Tokens

GitFig uses a Git-like workflow to track changes and push them to GitHub. Changes are automatically detected, then you stage, commit, and push.

Time: 5 minutes Difficulty: Beginner

The Commit Workflow​

GitFig follows a workflow similar to Git:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Make Changes   │ ──► │ Unstaged Changes│ ──► │ Staged Changes  │ ──► │ Commits to Push │ ──► GitHub
│  in Figma       │     │ (auto-detected) │     │ (ready to commit)│    │ (local commits) │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
                              Stage ──►            Commit ──►              Push ──►

Three Sections​

The GitFig panel shows three sections for tracking changes:

SectionPurpose
Unstaged ChangesChanges detected in Figma but not yet staged
Staged ChangesChanges ready to be committed
Commits to PushLocal commits waiting to be pushed to GitHub

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 automatically detects changes every 3 seconds and displays them in the Unstaged Changes section.

Change Types​

IconMeaning
+ (green)New variable or style added
~ (yellow)Existing variable or style modified
- (red)Variable or style removed

Step 2: Stage Changes​

Select which changes you want to include in your next commit:

  • Click Stage next to individual changes
  • Or click Stage All to stage everything

Staged changes move to the Staged Changes section.

tip

You can Unstage changes if you change your mind. Click the unstage button next to any staged change.

Step 3: Create a Commit​

Once you have staged changes, create a local commit:

Enter Commit Details​

FieldPurpose
Commit messageShort summary of changes (required)
Extended descriptionDetailed explanation (optional)

Commit message - A brief summary line (50 characters or less recommended):

  • "Update primary brand color to orange"
  • "Add new spacing tokens for mobile"
  • "Fix contrast issue on secondary color"

Extended description - Use this for additional context:

  • Why the change was made
  • Related design decisions
  • Links to design specs or tickets

Click Create Commit​

Click Create Commit to save your changes as a local commit. The commit moves to the Commits to Push section.

note

Creating a commit does NOT push to GitHub yet. Commits are stored locally and can be pushed later.

Step 4: Push to GitHub​

When you're ready to push your commits to GitHub:

  1. Review the commits in the Commits to Push section
  2. Click the Push X Commits button
  3. Wait for the push to complete

GitFig pushes all pending commits to your current branch on GitHub.

What Happens During Push​

  1. GitFig exports your current Variables and Styles to JSON
  2. Creates a commit on GitHub with your message
  3. Updates the baseline so new changes can be detected

Managing Commits​

View Commit Details​

Click on a commit in the Commits to Push section to expand it and see:

  • Commit message and description
  • List of changed items
  • When it was created

Delete a Commit​

If you want to discard a commit before pushing:

  1. Expand the commit
  2. Click the trash icon
  3. The changes will reappear in Unstaged Changes

Push Options​

Direct Push (Default)​

Commits directly to your current branch. Best for:

  • Personal projects
  • Quick iterations
  • When you have push access

Create Pull Request​

Instead of pushing directly, create a PR for review:

  1. Push your changes to a feature branch first
  2. Click Create Pull Request in the PR section
  3. Enter PR title and description
  4. Click Create PR

Best for:

  • Team projects requiring code review
  • Protected branches that require PRs
tip

The Create Pull Request option only appears when you're on a feature branch, not on main or master.

Conflict Detection​

If GitHub has commits you haven't pulled, GitFig shows a warning before push.

Options:

  • Push anyway - Your changes may overwrite remote changes
  • Pull first - Recommended: sync before pushing

What Gets Exported​

Variables → 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​

Your commits are stored in the cloud, so you can:

  • Create commits on one device
  • Push them from another device
  • See pending commits on any device with access

Troubleshooting​

Changes not appearing in Unstaged​

  • Wait a few seconds - detection runs every 3 seconds
  • Check that you have file mappings configured
  • Try closing and reopening the plugin

"Push failed: permission denied"​

  • Check you have write access to the repository
  • Branch may be protected - try creating a PR instead
  • Token may have expired - sign out and back in

Committed changes reappearing in Unstaged​

  • This shouldn't happen with the latest version
  • If it does, try pulling to reset the baseline

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 Extended Descriptions for Context​

Add an extended description when:

  • The change needs explanation beyond the summary
  • You want to link to design specs or tickets
  • Multiple related changes are bundled together

Commit Often​

Small, frequent commits are better than large, infrequent ones.

Pull Before Push​

Always pull latest changes before pushing to avoid conflicts.

Next Steps​