Variable Modes Preview

GitFig syncs all modes of your Figma variable collections (light/dark themes, brand variants, density scales) in both directions. Variable modes sync is free for everyone during the v1.3 preview. It becomes part of GitFig Pro in a future release, and pricing will be announced before that happens.

Quick Start with Example Files

Get a working two-collection setup: variable-modes includes a single-mode Primitives file, a light/dark Semantic file with alias references and $extensions, and color style and text style files that pull in too.

The mode-keyed file format

A mode-keyed token file uses mode names as root keys. Every mode contains the same token structure with different values:

{
  "light": {
    "color": {
      "bg": { "$value": "#ffffff", "$type": "color" },
      "text": { "$value": "{Primitives.gray.900}", "$type": "color" }
    }
  },
  "dark": {
    "color": {
      "bg": { "$value": "#111111", "$type": "color" },
      "text": { "$value": "{Primitives.gray.100}", "$type": "color" }
    }
  }
}

Values like {Primitives.gray.900} are alias references: they point to a variable in another collection (CollectionName.path.to.token, dots or slashes both accepted on import). GitFig writes aliases in this form on push and re-binds them to real variable aliases on pull.

Enabling modes on a mapping

Modes are configured per file mapping, because modes belong to collections and each mapping targets one collection:

1. Open your connected file's Mapping section.
2. Add or edit a mapping with target type Variables.
3. Under Variable Modes, choose All modes.

One file maps to one collection. A typical multi-mode setup:

File	Target	Modes
tokens/primitives.json	Variables → Primitives	First mode only
tokens/semantic.json	Variables → Semantic	All modes
tokens/color-styles.json	Color styles	n/a
tokens/text-styles.json	Text styles	n/a

Styles have no modes and always serialize flat.

Push behavior

• Each mapping produces its own file; all files go up in one atomic commit.
• A mode-keyed file's root keys exactly match the collection's mode names, in collection order.
• Single-mode collections mapped as "All modes" are still wrapped under their mode name, so the file shape never flips when you add a second mode.

Pull behavior

• Modes are matched to Figma by name (case-insensitive). Modes in the file that don't exist in Figma are added to the collection; modes in Figma absent from the file are left untouched.
• One variable receives one value per mode; pulling never duplicates variables.
• Structurally unequal modes (a token present in light but missing in dark) apply what exists. Nothing is ever deleted.
• An empty mode in the file (e.g. "dim": {}) creates the mode in Figma with no values applied. Figma seeds the new mode's values by copying the collection's default mode, and your next push then fills that mode in the file with its actual values.
• Legacy combined files sometimes carry colorStyles/textStyles/effectStyles as sibling root keys; those are ignored when pulling into Variables (map them to their own style targets instead).

Requirements and limits

• Free during the preview. Variable modes sync is included for everyone in v1.3. It becomes part of GitFig Pro in a future release.
• Your Figma plan sets the mode ceiling. Figma's Starter plan allows 1 mode per collection, so multi-mode sync cannot work there. Professional and higher plans allow more modes; if a pull would exceed your Figma plan's limit, GitFig applies the modes that fit and reports which were skipped.
• Mode names colorStyles, textStyles, and effectStyles are reserved and can't be used as mode names in synced collections.

After the preview

When variable modes sync becomes part of GitFig Pro, files you created during the preview stay yours and are never altered. The exact free-plan behavior for existing mode-keyed files will be announced with the Pro launch, ahead of the change taking effect.

The mode-keyed file guard

Any mapping set to First mode only refuses to import a file whose root keys look like modes (identically structured top-level groups). This prevents a mode-keyed file from being flattened into broken variables like dark/colors/primary. To import such a file, set the mapping's Variable Modes to All modes. If the file genuinely isn't mode-keyed (two ordinary groups with identical structure), split those groups into separate files.

Team notes

During the preview every teammate can pull and push mode-keyed files. When GitFig Pro launches, the entitlement will be per Figma account; how that applies to teams and to files created during the preview will be part of the launch announcement.