Skip to main content

File Mappings

File mappings tell GitFig which JSON files in your repository should sync with which Figma elements. This guide explains how to configure them.

Time: 5 minutes Difficulty: Beginner

What Are Mappings?​

A mapping connects a JSON file in GitHub to a target type in Figma:

JSON File→Target Type
tokens/colors.json→Variables
tokens/typography.json→Text Styles
tokens/effects.json→Effect Styles

Configure Mappings​

Step 1: Open Configuration​

Click "Configure" next to "Sync Mappings" in the GitFig panel.

Configure Button

Step 2: Browse Repository​

The file browser shows your repository structure:

File Browser

  • Click folders to expand/collapse
  • Click JSON files to select them
  • Non-JSON files are grayed out

Step 3: Select Target Type​

After selecting a file, choose what it should sync with:

Target TypeWhat It CreatesBest For
VariablesVariable CollectionsColors, numbers, strings, booleans
Color StylesColor StylesLegacy color styles
Text StylesText StylesTypography definitions
Effect StylesEffect StylesShadows, blurs

Step 4: Add Mapping​

Click "Add Mapping" to add it to your list.

Add Mapping

Step 5: Save​

Click "Save Mappings" to save your configuration.

Multiple Mappings​

You can add multiple mappings to sync different files:

tokens/colors.json     → Variables
tokens/typography.json → Variables
tokens/effects.json    → Effect Styles
legacy/colors.json     → Color Styles

Mapping Examples​

Basic Token Setup​

tokens/
├── colors.json    → Variables
├── spacing.json   → Variables
└── typography.json → Variables

Multi-File Organization​

design-system/
├── foundations/
│   ├── colors.json      → Variables
│   ├── spacing.json     → Variables
│   └── typography.json  → Variables
├── components/
│   └── button.json      → Variables
└── themes/
    ├── light.json       → Variables
    └── dark.json        → Variables

Mixed Targets​

tokens/
├── variables.json  → Variables
├── typography.json → Text Styles
└── effects.json    → Effect Styles

Token Format Auto-Detection​

GitFig automatically detects the token format of each file:

FormatDetectionExample
W3CHas $value and $type{"color": {"$value": "#fff", "$type": "color"}}
Style DictionaryHas value without ${"color": {"value": "#fff"}}
Tokens StudioHas type and value{"color": {"value": "#fff", "type": "color"}}
CustomFlat key-value pairs{"primary": "#fff"}

You can override auto-detection by selecting a specific format in the mapping dialog.

Edit Existing Mappings​

To modify a mapping:

  1. Open the Configure dialog
  2. Click the edit icon next to the mapping
  3. Change the target type or format
  4. Save changes

Remove Mappings​

To remove a mapping:

  1. Open the Configure dialog
  2. Click the delete icon next to the mapping
  3. Confirm removal
  4. Save changes
warning

Removing a mapping doesn't delete the Variables or Styles in Figma. It just stops syncing that file.

Best Practices​

One File Per Collection​

Map each JSON file to create one Variable Collection:

colors.json → "colors" collection
spacing.json → "spacing" collection

Consistent Naming​

Use the same structure in JSON and Figma:

// colors.json
{
  "brand": {
    "primary": { "$value": "#0066FF", "$type": "color" }
  }
}

Creates variable: brand/primary

Start Small​

Begin with one or two files, verify they work, then add more.

Troubleshooting​

"File not found in mapping"​

  • The file may have been renamed or deleted on GitHub
  • Re-configure the mapping with the correct file path

"No tokens found in file"​

  • Check that the JSON is valid
  • Ensure tokens have the required $value field
  • Verify the file isn't empty

Variables not updating​

  • Check that the mapping is saved
  • Verify you clicked "Pull" after saving
  • Look for errors in the browser console

Next Steps​

With mappings configured, you're ready to: