Skip to content

Aliases

All aliases are converted into the alias string format from the Design Tokens specification.

{
"button": {
"background": {
"type": "color",
"value": "{colors.primary.10}"
}
}
}

References use . as separator, so DTCG forbids ., { and } in token and group names. A collection whose name contains them, like 1. Primitives, is exported as 1- Primitives, with a warning; the meta keeps the original name, and the import uses it to recreate the collection under its Figma name.

You can switch on the Include .value string for aliases option in the plugin settings.

Since September 2026 Figma lets a color variable alias another color and apply its own opacity on top (“Control opacity at scale”). The opacity can be a plain percentage or a number variable with the COLOR_OPACITY scope.

The DTCG color type has no way to express “this color, with that opacity” while keeping the reference, so the plugin exports these variables as a composite value: components holds the reference to the base color and alpha holds the opacity, as a 0..1 number (or "50%" with Use percentage for opacity) or a reference to the number variable driving it.

{
"opacity": {
"50": { "$type": "number", "$value": 0.5, "scopes": ["COLOR_OPACITY"] }
},
"color": {
"brand": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.2, 0.4, 0.8],
"alpha": 1,
"hex": "#3366cc"
}
},
"brand-translucent": {
"$type": "color",
"$value": { "components": "{color.brand}", "alpha": 0.5 }
},
"brand-muted": {
"$type": "color",
"$value": { "components": "{color.brand}", "alpha": "{opacity.50}" }
}
}
}

The alpha is the opacity Figma applies on top of the referenced color. If the base color is a literal rather than an alias, the opacity is baked into the regular color value for the chosen color mode; only when the opacity itself is a reference does the color value keep an alpha (or a) reference in place of the number.

Importing these tokens recreates the composed color variable in Figma: components becomes the alias, alpha the opacity (a plain percentage or an alias to the number variable). References to variables in other collections are resolved once every collection has been imported.

Figma has exposed these variables to plugins in two shapes so far: current runtimes (the Figma web app, and what setValueForMode accepts) use { "color": <alias or rgba>, "opacity": <0..100 or alias> }, while Figma Desktop 126.x returned a COMPOSE_COLOR expression. The export reads both. The import writes the current shape and falls back to the expression for runtimes that only accept that one.

Imagine you have a library from another file with “base” variables. And you use this variables in your current file.

The plugin will generate the alias name anyway, but it will be a path to the variable as if it was in the current file.

{
"button": {
"background": {
"type": "color",
"value": "{colors.primary.10}"
}
}
}

The plugin wouldn’t include the variable into the generated JSON in order to avoid duplicates or conflicts with JSON files you can generate from another Figma files. The CLI and the library API do the same in REST mode. In snapshot mode, add the library variables and their collections with "remote": true: they resolve aliases but aren’t exported.

So you will need to merge the file with the base variables from one file with another where you use them. Otherwise tools like Style Dictionary wouldn’t be able to resolve the aliases.

If there is only one mode, the mode values are left out: $extensions.mode is an empty object. If there are multiple modes, the plugin will place them under the $extensions objects.

It follows the same pattern as used by Cobalt