Wwds Variables

One gap is the lack of composite tokens. You can’t put a box shadow behind a single variable. That is an effect style, but style values can be bound to variables. Similarly for a type ramp, you have to use Text Styles.

Model

Collections

Collections can be thought of a groups in Figma. An example Collection would be “Colors” where there might be a light and dark “Mode.” Each value would have two definitions.

Extended Collections

Extended collections allow you to create a colleciton based on another collection and only override some of the values. Just like inheritance and overrides in CSS. This aligns well for scenarios like branded color themes.

Modes

Modes in Figma can be thought of like light and dark, but users can specify modes for anything, including sizes, languages (string variables exist in Figma too).

Aliasing

Aliasing in Figma variables is simply when you point a variable to another variable. Common example is pointing a semantic variable to a primitive variable. Some teams also do component level tokens which adds a third component specific layer.

Decision rule: If the source data has two tiers (primitives + semantics), create all primitives first, then create semantic variables that alias into them. If the source data is a single flat tier, create flat variables with no aliases. When in doubt, ask.

Code Syntax

Code syntax is a surface area in Figma for codebase translation context. You can set WEB, iOS, and ANDROID code syntax on any variable, and when that variable is referenced in other places (visually in Figma’s dev mode, as design context via MCP), this codebase form will appear. These are best thought of as “instance” documentation, eg. var(--the-thing) instead of --the-thing in the case of CSS.

Scope

variable.scopes: VariableScope[] specifies which properties in Figma the variable can be used for. This is important when you create and when you use variables. It is always better to use scopes than not or to set it to be ALL_SCOPES. The more specific the better, but not all variable collections are complex enough to account for precision here.

Common scope values:

• ALL_SCOPES — unrestricted; use when precision isn’t required
• FILL_COLOR, STROKE_COLOR — color bindings
• TEXT_CONTENT — string variables for text layers
• FONT_SIZE, FONT_WEIGHT, LINE_HEIGHT, LETTER_SPACING — typography
• CORNER_RADIUS, WIDTH_HEIGHT, GAP — layout/spacing
• OPACITY — layer opacity

Grouping

Variable names in Figma are slash delimited and each slash represents a group that is visualized in Figma. When you are doing matching, consider a part of a code prefix might be the name of the collection, not a top level group. Sometimes you will have prefixes in code that aren’t in Figma, and that can be ok, just be sure to ask if it is unclear. You can always validate existing variables by referencing the code syntax.

Common gotchas

• createVariableCollection always creates a default mode — you will need to rename it (or delete it and add your own) rather than creating from scratch.
• Duplicate variable names throw silently — Figma does not error; it creates a second variable with the same name. Always check for existence before creating.
• Variable aliases require the target to be in the same file — cross-file aliasing is not supported via the plugin API. If you need to alias to a library variable, import it first.
• setValueForMode with an alias requires the exact shape — { type: 'VARIABLE_ALIAS', id: '<variableId>' }. Any deviation will silently set the wrong value or throw.

Usage guidelines

• Creating variables: What you must consider when creating new variables.
• Using variables: What you must consider when trying to use the right variables.

Code patterns

For runnable code examples (creating collections, binding variables, scopes, aliasing, discovering existing variables), see variable-patterns.md.