Skip to main content

Pushing Tokens

Pushing exports your Figma Variables and Styles to JSON and commits them to GitHub.

Time: 3 minutes Difficulty: Beginner

How Push Works​

When you click Push, GitFig:

  1. Reads Variables and Styles from Figma
  2. Converts them to W3C Design Tokens JSON format
  3. Creates a commit with your message
  4. Pushes to your current branch on GitHub
Figma                     GitFig                     GitHub
─────                     ──────                     ──────
Variable Collection  ───►  Export JSON  ────────►   colors.json
├── primary: #0066FF      Format tokens             commit: "Update colors"
├── secondary: #6B7280    Create commit             push to main
└── background: #FFFFFF

Perform a Push​

Step 1: Make Changes in Figma​

Edit your Variables or Styles in Figma:

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

Step 2: Click Push​

Click the Push button in GitFig.

Push Button

Step 3: Enter Commit Message​

Write a descriptive commit message:

Commit Message

Good commit messages:

  • "Update primary brand color to orange"
  • "Add new spacing tokens for mobile"
  • "Fix typo in typography descriptions"

Step 4: Push to GitHub​

Click "Push to GitHub" to commit and push.

Step 5: Verify on GitHub​

Open your repository on GitHub to see the new commit:

GitHub Commit

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": {...}}}

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. Click the dropdown arrow next to Push
  2. Select "Create Pull Request"
  3. Enter PR title and description
  4. Select base branch (usually main)
  5. Click "Create PR"

Create PR

Best for:

  • Team projects
  • Design reviews
  • Protected branches

Conflict Detection​

If GitHub has commits you haven't pulled, GitFig shows a warning:

Push Conflict

Options:

  • Push anyway - May cause merge conflicts
  • Pull first - Recommended: sync before pushing
  • View changes - See what's different on GitHub

Files Updated​

Push updates the JSON files based on your mappings:

MappingFile Updated
colors.json → VariablesUpdates colors.json
spacing.json → VariablesUpdates spacing.json
note

Push only updates files you have mappings for. Other files in the repo are unchanged.

Commit History​

Each push creates a Git commit. View history:

  • On GitHub: Repository → Commits
  • In GitFig: Shows last sync commit SHA

Troubleshooting​

"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

"No changes to push"​

  • No Variables have changed since last sync
  • Check you're editing the correct collection

JSON formatting different than expected​

  • GitFig always exports in W3C format
  • Other formats are converted on export
  • Formatting/whitespace may change

Large commits taking long​

  • Many variables = larger JSON files
  • Network affects upload speed
  • Consider splitting into multiple files

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"

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​