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​

The Mapping section at the bottom of the linked panel shows your repository's JSON files and their targets. It stays open while setup is incomplete (no mappings, or a mapping that has not been pulled yet) and collapses to its header row, Mapping · 4 files, once every mapping has pulled. Click the header to open it again.

The File Tree​

  • Folders start expanded; click a folder to collapse or expand it
  • JSON files are shown and can be mapped
  • Non-JSON files are hidden (they cannot be used for token sync)
  • The refresh icon in the header re-reads the repository; the tree also refreshes after a pull and when new commits land on the branch

Adding a Mapping​

  1. Hover a JSON file (or Tab to it) and click Add target
  2. In the dialog:
    • Select the target type (Variables, Color styles, Text styles, Effect styles)
    • Select the token format (Auto-detect recommended)
    • For Variables targets, set the collection name; it must match the Figma collection you want exported to this file (defaults to the file name)
    • For Variables targets, choose Variable modes: First mode only (default) or All modes (Variable Modes, free during the preview) for mode-keyed files
  3. Click Add mapping. The mapping is saved immediately
  4. The section shows "Pull to import primitives.json" (your file name) with a Pull link; adding a mapping does not import anything by itself. The section stays open until that first pull succeeds
Target TypeWhat It CreatesBest For
VariablesVariable CollectionsColors, numbers, strings, booleans
Color stylesColor stylesLegacy color styles
Text stylesText stylesTypography definitions
Effect stylesEffect stylesShadows, blurs

Mapped rows​

A mapped file shows its target after an arrow, for example semantic.json → Variables · Semantic. Hover the row (or Tab into it) to reveal the edit and remove buttons; clicking the row also opens the editor.

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

With multiple mappings, each push writes every mapped file in a single atomic commit, one file per mapping. (A single legacy Variables mapping keeps the original combined-file output.)

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. Click the mapped row (or its pencil icon)
  2. Change the target type, format, collection name, or variable modes
  3. Click Save

Remove Mappings​

To remove a mapping:

  1. Hover the mapped row and click the trash icon
  2. Confirm Remove in the row that appears
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: