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 in GitFig shows your repository file tree and current mappings inline in the main view.

The File Tree​

The left side of the Mapping section displays your repository structure:

  • Click folders to expand/collapse
  • JSON files are shown and can be mapped
  • Non-JSON files are hidden (they can't be used for token sync)

Adding a Mapping​

  1. In the Mapping section, browse the file tree
  2. Hover over a JSON file you want to map
  3. Click the "+ Add Target" button that appears
  4. An expansion panel opens inline:
    • Select the target type (Variables, Color Styles, etc.)
    • Select the format (Auto-detect recommended)
  5. The mapping is saved automatically
Target TypeWhat It CreatesBest For
VariablesVariable CollectionsColors, numbers, strings, booleans
Color StylesColor StylesLegacy color styles
Text StylesText StylesTypography definitions
Effect StylesEffect StylesShadows, blurs

The Mappings List​

The right side shows your configured mappings. Each mapping displays:

  • The file path (e.g., tokens/colors.json)
  • The target type and collection name

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. Click on the mapping in the mappings list
  2. An inline edit panel opens
  3. Change the target type or format
  4. Changes save automatically

Remove Mappings​

To remove a mapping:

  1. Hover over the mapping you want to remove
  2. Click the delete icon that appears
  3. Confirm removal
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: