Token Formats

GitFig supports multiple design token formats. This guide explains each format and how to use them.

Time: 5 minutes Difficulty: Intermediate

Supported Formats

Format	Detection	Recommendation
W3C Design Tokens	$value + $type	✅ Recommended
Style Dictionary	value (no $)	Good for Amazon SD users
Tokens Studio	value + type	Good for TS migration
Custom JSON	Any structure	Flexible but limited

W3C Design Tokens (Recommended)

The W3C Design Tokens format is the emerging standard.

Structure

{
  "colors": {
    "primary": {
      "$value": "#0066FF",
      "$type": "color",
      "$description": "Primary brand color"
    },
    "secondary": {
      "$value": "#6B7280",
      "$type": "color"
    }
  },
  "spacing": {
    "small": {
      "$value": 8,
      "$type": "number"
    },
    "medium": {
      "$value": 16,
      "$type": "number"
    }
  }
}

Properties

Property	Required	Description
$value	✅ Yes	The token value
$type	✅ Yes	Type of token
$description	No	Human-readable description
$extensions	No	Tool/pipeline metadata; preserved by GitFig, never modified

Repo-owned metadata is safe

GitFig only writes $value, $type, and token-level $description (they always reflect Figma). Everything else that is $-prefixed ($extensions, $deprecated, custom metadata on tokens or groups) survives pushes untouched.

Types

$type	Figma Variable	Example $value
color	COLOR	"#0066FF", "rgb(0, 102, 255)"
number	FLOAT	16, 1.5
dimension	FLOAT	"16px", "1rem"
string	STRING	"Inter", "bold"
boolean	BOOLEAN	true, false

Nesting

Groups are created by nesting objects:

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

Creates variable: brand/colors/primary

Style Dictionary

Style Dictionary is Amazon's token format.

Structure

{
  "color": {
    "brand": {
      "primary": {
        "value": "#0066FF"
      },
      "secondary": {
        "value": "#6B7280"
      }
    }
  },
  "size": {
    "spacing": {
      "small": {
        "value": "8px"
      }
    }
  }
}

Detection

GitFig detects Style Dictionary when:

• Objects have value property (without $ prefix)
• No $value present

Conversion

On pull, GitFig converts to Figma Variables:

• value: "#0066FF" → COLOR variable
• value: "8px" → FLOAT variable (8)

On push, GitFig exports as W3C format (not Style Dictionary).

Tokens Studio

Tokens Studio is a popular Figma plugin for design tokens.

Structure

{
  "global": {
    "colors": {
      "primary": {
        "value": "#0066FF",
        "type": "color"
      },
      "secondary": {
        "value": "#6B7280",
        "type": "color"
      }
    },
    "spacing": {
      "sm": {
        "value": "8",
        "type": "spacing"
      }
    }
  }
}

Detection

GitFig detects Tokens Studio when:

• Objects have value AND type properties
• No $ prefix

Conversion

Tokens Studio type	Figma Variable
color	COLOR
spacing	FLOAT
sizing	FLOAT
borderRadius	FLOAT
fontFamilies	STRING
fontWeights	STRING
fontSizes	FLOAT

Migration from Tokens Studio

See the Migration Tutorial for step-by-step instructions.

Custom JSON

For simple use cases, GitFig can parse flat JSON structures.

Structure

{
  "primaryColor": "#0066FF",
  "secondaryColor": "#6B7280",
  "spacingSmall": 8,
  "spacingMedium": 16,
  "fontFamily": "Inter"
}

Detection

GitFig treats JSON as custom when:

• Values are primitives (strings, numbers, booleans)
• No nested token objects

Type Inference

Without explicit types, GitFig infers:

Value	Inferred Type
"#0066FF"	COLOR
"rgb(0,0,0)"	COLOR
16	FLOAT
"Inter"	STRING
true	BOOLEAN

Limitations

• No descriptions
• No grouping
• Type inference may be wrong

Color Value Formats

GitFig supports multiple color formats:

Format	Example
Hex (6-digit)	"#0066FF"
Hex (8-digit, with alpha)	"#0066FF80"
Hex (3-digit)	"#06F"
RGB	"rgb(0, 102, 255)"
RGBA	"rgba(0, 102, 255, 0.5)"
HSL	"hsl(220, 100%, 50%)"
HSLA	"hsla(220, 100%, 50%, 0.5)"

Dimension Values

Dimensions are parsed to numbers:

Input	Parsed Value
16	16
"16px"	16
"1rem"	16 (assumes 16px base)
"1.5em"	24 (assumes 16px base)

Format Override

You can override auto-detection in the file mapping:

1. Open Configure
2. Select a file
3. Choose specific format from dropdown
4. Save mapping

Export Format

When pushing, GitFig always exports in W3C format, regardless of the source format. This ensures consistency.

Best Practices

Use W3C Format

The W3C format is:

• Standardized
• Well-documented
• Future-proof
• Most explicit

Include Types

Always specify $type for clarity:

// Good
{ "$value": 16, "$type": "number" }

// Avoid
{ "$value": 16 }

Use Descriptions

Add $description for documentation:

{
  "primary": {
    "$value": "#0066FF",
    "$type": "color",
    "$description": "Main brand color, used for CTAs and links"
  }
}

Next Steps

• Token Format Reference for complete specification
• Migration from Tokens Studio