Variables store reusable values, such as colors and numbers, that can be applied across a design. A note beside a variable explains when to use it. The distinction matters: a beautifully worded note cannot repair a collection in which “blue 3,” “primary blue,” and “button blue” all refer to overlapping purposes.
Separate raw values from design roles
Start with the roles the interface needs: page surface, body text, primary action, muted border, and so on. A raw color value may be shared by several roles today, but those roles can change independently later. Figma supports aliases, where one variable references another of the same type. Its variables overview explains values, collections, groups, aliases, and modes.
The names below are illustrative, not tokens from a real project. They show the difference between a value and a purpose:
| Example name | Role | Usage note to check |
|---|---|---|
| color/blue/600 | Raw color value | Do not use its number alone as a component rule. |
| color/action/primary | Semantic action color, potentially aliased to a raw color | Use for the main action’s background in the specified mode; test its label and states. |
| color/surface/subtle | Low-emphasis surface | Use behind secondary content; check text contrast on the actual surface. |
| space/section/gap | Spacing value | Use between major sections, not within a compact button. |
Use a consistent naming scheme that matches the team’s components and code. Figma groups variables within collections and supports context-specific modes such as light and dark themes. Mode availability can depend on plan, so check the current Figma modes documentation before building a workflow around it.
Write notes from the approved file
Export or copy the actual variable list and a few examples of where each variable is applied. Give the AI assistant this material, along with the naming rules. Ask for one-sentence notes that explain use and an important exclusion. A generic description such as “a vibrant color that enhances engagement” tells a designer nothing about where the variable belongs.
Draft usage notes for the variables listed below. Preserve every name, value, alias, and mode exactly as supplied. For each variable, state its intended component or surface and one common misuse. If the file does not establish a use, write “needs designer decision” rather than guessing. Do not create new variables.
Review the output with a component open beside it. If color/action/primary is used for a button background, the note should not say it is the button’s text color. If the same token changes in dark mode, the note should describe the role across modes, not hard-code one hex value as the universal answer.
Test the notes against changes
- Change a raw color value. Does the semantic role still make sense?
- Switch a mode where available. Does the note remain true for both contexts?
- Inspect a component. Can a new designer choose the right variable from the note without guessing?
- Check that typography styles and variables are documented accurately; a composite text style is not the same thing as one raw variable.
Figma’s documentation distinguishes styles and variables: styles can combine values, while variables hold reusable values and can support modes. Keep that technical distinction in the notes. The goal is a small set of instructions that helps someone make a correct design choice, not a long glossary produced for its own sake.
