figma variables, explained without the marketing: what they are, when they help, when they hurt

design · 2024-05-17 · 7 min

figma variables are one of those features that sound like a small thing and turn out to be a different way of organizing a file. the marketing says "one source of truth". that is true. it is also incomplete, because a source of truth is only useful if the path to it is shorter than the path around it.

this is the plain version: what variables are, when they help, and when they make a simple file harder.

what a variable is

a variable is a named value. the value can be a color, a number, a string, or a boolean. you give it a name, you use the name in your design, and when the value changes, every place that uses the name changes with it.

a collection is a group of variables. a mode is a variant of a collection. light and dark are modes. comfortable and compact are modes. a brand a and brand b are modes. the collection holds the names; the mode holds the values.

that is the whole model. the complexity is not in the concept. it is in the naming and the layers.

the difference from styles

styles came first. a color style is a named color. a text style is a named set of type properties. variables are more general: they can hold a number, a string, a boolean, and they can be swapped by mode.

for a single-theme project, styles are enough. for a project with a second mode, variables start to earn their place, because a style cannot change its value when the mode changes. a variable can.

the practical rule: start with styles, add variables when the second mode appears. not before. a variable layer with one mode is indirection without a payoff.

when they help

light and dark. the classic case. one semantic name, two values, one switch. without variables you duplicate the file or you maintain two sets of styles and hope they stay in sync.

multiple brands. the same component library with different palettes. a brand mode swaps the values without touching the component. this is the case where variables are not a convenience but a requirement.

density. compact and comfortable spacing. a number variable for the spacing scale, a mode for the density. the components do not know which one they are in.

handoff. a semantic name is easier for a developer to map to a token than a raw hex value. surface-raised is a better contract than #f5f3f7.

when they hurt

one mode, small project. the extra layer adds a step to every change and buys nothing. a two-page site with one theme does not need a variables architecture. it needs consistent styles.

too many semantic layers. primitives, aliases, semantic tokens, component tokens, and a mode for each. every layer is a place where the name can drift from the meaning. after three layers, nobody knows which one to edit.

naming debt. a variable called blue-500 is a value. a variable called accent is a role. a variable called accent-old is a decision nobody documented. variables make naming debt visible and then make it worse, because the name is now used everywhere.

design-code mismatch. a variable library that does not match the code tokens is a second source of truth, not a single one. the mismatch is worse than no variables, because it looks authoritative.

the structure i use

two layers, not five.

primitives: gray-100, gray-900, blue-500, space-4, radius-8. the raw values. never used directly in a component.

semantic: surface, surface-raised, text, text-muted, accent, border, danger. the roles. these are what components use, and these are what modes swap.

two modes: light and dark. a third mode only when a real brand or density requirement exists. a naming rule: if the name describes a color, it belongs in primitives. if it describes a job, it belongs in semantic.

the honest trade-off

variables are a tool for scale. they pay off when the number of combinations is larger than the number of components. they cost when the number of combinations is one, because the indirection is pure overhead.

the mistake i see most often is a team adopting variables because they are the modern thing, then spending a month naming a system that has one mode and no second brand. the second mistake is a team with two brands and no variables, duplicating every component and calling it a design system.

match the tool to the combinations. that is the whole decision.

for the design-code drift side, see figma component drift. for the ai features in the same tool, see the ai features in figma.