Syncing Overview

GitFig connects Figma files directly to GitHub repositories for bi-directional sync of design tokens, variables, and styles.

What GitFig Does

GitFig allows you to:

• Pull JSON token files from GitHub and create/update Figma Variables and Styles
• Push Figma Variables and Styles back to GitHub as JSON
• Branch to work on different design variations
• Create PRs to review design changes before merging

┌─────────────────────────────────────────────────────────────────────┐
│                    DESIGN FILE SYNC                                 │
│                                                                     │
│   GitHub Repository                    Figma Design File            │
│   ─────────────────                    ─────────────────            │
│                                                                     │
│   branches:                            Synced Elements:             │
│   ├── main                             ├── Variables                │
│   ├── feature/new-theme                ├── Color Styles             │
│   └── experiment/bold-colors           ├── Text Styles              │
│                                        └── Effect Styles            │
│   files:                                                            │
│   ├── tokens/colors.json      ←→       Color Variables              │
│   ├── tokens/typography.json  ←→       Text Styles                  │
│   └── tokens/spacing.json     ←→       Number Variables             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Features

Bi-Directional Sync

Direction	What Happens
Pull (GitHub → Figma)	Reads JSON files, creates/updates Variables and Styles
Push (Figma → GitHub)	Exports Variables/Styles to JSON, commits to repository

Token Format Support

GitFig supports multiple token formats:

• W3C Design Tokens (recommended) - Standard format with $value and $type
• Style Dictionary - Amazon's token format
• Tokens Studio - Popular Figma plugin format
• Custom JSON - Any JSON structure with color/number values

Branch Workflows

Work on different design variations using Git branches:

• Switch branches to load different token values
• Create new branches for experiments
• Create pull requests for design reviews
• Merge branches when ready

Change Detection

GitFig automatically detects changes in real-time:

• Local changes - Detects when you modify Variables or Styles in Figma (every 3 seconds)
• Remote changes - The Pull button turns blue with the number of new commits on GitHub, and the latest commit message appears under the header
• Conflict warnings - Pushing over commits you have not pulled asks first (Pull first, or Push anyway); pulling over uncommitted changes asks too, and every pull can be undone in one step

Commit Workflow

Push your changes with a Git-style flow:

1. Changes - Detected changes, each with a checkbox; checked changes go into the next commit
2. Commit - Write a message and commit the checked changes
3. Ready to push - Commits waiting to be pushed to GitHub, with Push always one click away

This gives you full control over what gets committed and when.

When to Use GitFig

Good for:

• Design token management
• Multi-brand/multi-theme systems
• Design system documentation
• Collaborative design reviews

Not needed for:

• Single-designer projects without developers
• Projects without version control requirements
• Files that don't use Variables or Styles

Getting Started

1. Connect a Repository
2. Configure File Mappings
3. Pull Your First Tokens