A practical naming guide for Figma variables

Variable naming is not clerical work. It is how a team explains which design decisions are stable, which are contextual, and which are allowed to change.

When names are weak, the system becomes hard to use even if the values are correct. Designers cannot tell which variable belongs on a component. Engineers cannot map Figma intent to CSS. Reviewers cannot tell whether a one-off value is a mistake or a new need.

The goal of naming is not elegance. The goal is predictability under deadline pressure.

Use layers before clever names

I use three naming layers for most product systems:

1. Primitive variables for raw values.
2. Semantic variables for intent.
3. Component variables for specific component behavior.

The layers matter more than the separator style. You can use slash groups in Figma, dot notation in JSON, or kebab-case in CSS. The important part is that everyone understands what layer they are using.

Primitive variables

Primitive names should describe the material, not the purpose.

Good:

color/green/500
color/gray/900
space/4
radius/2
shadow/raised

Avoid:

color/button-green
color/success-background
space/card-padding

Those second examples are trying to do semantic work inside the primitive layer. That makes the system harder to theme because the raw value now carries product meaning.

Primitives are the palette. They are not the interface.

Semantic variables

Semantic variables are the daily working language:

color/bg/page
color/bg/surface
color/text/default
color/text/muted
color/border/default
color/action/primary/bg
color/action/danger/bg

These names answer "what job is this value doing?" That makes them more durable than visual names. A redesign can change the primary action from green to black while the semantic variable remains correct.

Semantic variables are also easier to discuss in critique. "This should use color/text/muted" is clearer than "make it the other gray."

Component variables

Component variables are useful when a reusable component has stateful behavior that deserves local names.

button/primary/bg
button/primary/text
button/primary/hover-bg
input/focus/ring
card/elevated/border

The risk is overuse. If every component has its own full color system, the product will drift. Component variables should usually alias semantic variables, not replace them.

Think of component variables as an interface for implementation details. They help designers and engineers talk about a component without losing the connection to product-wide intent.

Modes should describe real product contexts

Light and dark are obvious modes. High contrast can be a mode. Brand variants can be modes when the product genuinely supports multiple brands.

Modes should not become a dumping ground for temporary campaigns or visual experiments. Every mode multiplies the maintenance cost. If you add a mode, every semantic variable needs a responsible value in that context.

A useful mode name answers "when is this active?"

Good:

Mode: Light
Mode: Dark
Mode: High contrast
Mode: Brand / Merchant

Weak:

Mode: Cool
Mode: Fancy
Mode: New homepage

Keep names boring enough to remember

The best naming systems are slightly boring. They do not require a glossary for every decision. If a new teammate has to ask whether the right token is color/text/subtle, color/text/secondary, color/text/muted, or color/text/quiet, you probably have too many near-synonyms.

Pick fewer words and reuse them consistently:

• default
• muted
• strong
• primary
• danger
• success
• warning

Do not invent a new adjective unless the product meaning is truly different.

The handoff test

The naming system is working when handoff becomes predictable. A designer applies color/action/primary/bg in Figma. An engineer sees the same name in CSS. A reviewer can spot when a new screen uses a local hex value instead of the semantic token.

A migration path for messy files

Most teams do not get to start from a clean variable system. They inherit old color styles, duplicated names, campaign leftovers, and component-specific values that nobody wants to delete because something might still use them.

The safest migration path is to create the new layers next to the old ones, move one product surface at a time, and mark old variables as deprecated only after usage is visible. Do not rename everything at once. Renaming without adoption work creates a different kind of confusion.

I like to start with the variables used by buttons, forms, cards, navigation, and page backgrounds. Those decisions appear everywhere, so the naming model becomes visible quickly. Once the common surfaces are stable, charts, illustrations, and marketing-specific styles can follow.

Review the names in real components

Do not review variable names only in a spreadsheet. Apply them to real Figma components and inspect the result with an engineer. The question is not "does this name look tidy?" The question is "would this name tell someone what to implement?"

If the answer is no, the name needs more work.

That is the practical value of naming. It turns visual choices into shared product language.