Naming variables without boxing yourself in

Why the name matters more than the value

A value is easy to change. You shift a blue from one shade to another, and every page follows. A name, on the other hand, gets copied everywhere: into components, into documentation, into code. Renaming it means redoing all of that.

A good name answers a single question: when I need to pick this variable, do I know right away that it's the right one? If answering means opening the variable to check its value, the name isn't doing its job.

Two ways to name: by hue or by role

There are two broad families of names, and most mistakes come from mixing them without ever deciding to.

By hue. The variable says what it is: blue, sand, ink, light gray. It's readable, immediate, and it matches the way people talk about colors in meetings.

By role. The variable says what it's for: background, primary text, secondary text, border, action, error. You don't know which color sits behind it, but you know where to use it.

Neither is better in absolute terms. They meet different needs.

When to name by hue

I name by hue when the palette is short and the product has only one theme. Five or six colors, each with a clear name, are often enough for a website or a small product.

In that case, role names add a layer without adding anything. If “background” is always “sand” and “text” is always “ink,” you have two names for the same thing. Everyone ends up using one or the other at random.

Naming by hue also has a quality I like: it makes the number of colors visible. When someone wants to add one, they have to give it a name, and that's often the moment you realize it isn't needed.

It has one clear limit: it doesn't survive a theme change. A variable called “white” that turns dark gray in dark mode is lying. From that point on, you need to switch to roles.

When to name by role

I name by role as soon as the same intent needs to take several values:

• a light mode and a dark mode;
• several brands or several clients on the same product;
• a product large enough for colors to carry meaning, such as success, warning, or error.

In those cases, the component shouldn't know what color it is. It knows it displays primary text on a card background, and the mode decides the rest.

Both together, without getting lost

On a growing product, you combine the two in two tiers and follow one simple rule: each tier has its own audience.

1. The hue tier, which holds the raw palette: the blues, the grays, the reds. Nobody uses it directly in mockups.
2. The role tier, which points to the hues: primary text maps to a dark gray in light mode and to a very light gray in dark mode. It's the only tier used in components.

To make the rule stick, I hide the hue tier in Figma so it doesn't show up in the color picker. What you can't see, you can't use by mistake.

I stop at two tiers. A third, component-specific tier, like “primary button background on hover,” makes sense for a library shared by many teams. For most products, it's one more layer of names to maintain for a benefit nobody will ever see.

Spacing and typography

Colors get all the attention, but spacing and text styles raise the same questions.

For spacing, I name by scale, not by value. A name like “space 16” looks clear, but it becomes wrong the day the value changes to 20 on desktop. I prefer a sequence of sizes, from smallest to largest, or a step-based numbering. The value can then change by mode without the name lying.

For typography, I name by role in the hierarchy: page title, section title, body text, caption. Never by size or weight. “Text 14 bold” doesn't tell you when to use it, and it becomes wrong as soon as you adjust the size on mobile.

In both cases, the rule is the same as for colors: the name describes what doesn't change, the value carries what does.

The traps I see most often

Putting the value in the name. “Blue 500,” “space 24,” “text 16.” These names feel comfortable at first and are wrong after the first tweak. If the value is in the name, nobody dares to change it anymore.

Naming after a screen. “Homepage background,” “contact form border.” The day the same color is needed elsewhere, you either reuse it under a misleading name or create a duplicate.

Naming after a feeling. “Nice blue,” “soft gray,” “bright red.” These names don't help you choose between two variants, and everyone reads them their own way.

Mixing languages. Half the variables in French, the other half in English, and abbreviations in between. I pick one language at the start of the project and write it into the file's rules.

Leaving synonyms. “Main,” “primary,” and “brand” all pointing to the same color. Every synonym is a question someone will ask later, or worse, one they won't ask.

Getting granular too early. Creating forty role variables before drawing a single component. You invent needs that don't exist yet. I start small and add a role when a real case calls for it.

Names shared with the code

A variable name doesn't belong to the designer. It will be typed by a developer, read in a code review, searched for in an internal search tool. So it has to work in both worlds.

Here are the rules I follow to make that happen:

• a group structure, from most general to most specific: category, then role, then variant. Figma organizes groups with a slash, and code often translates them with a hyphen. The structure stays the same;
• no accents, no spaces, no special characters in the names themselves, even when writing in French. What works in Figma doesn't always work in code;
• the same words on both sides. If Figma says “secondary text,” the code doesn't say “muted text.” Two vocabularies always end up producing two products;
• a choice made with the developers, not presented as a done deal. They know which conventions already exist in the code, and they're the ones who will type these names every day.

I've already explained why I route every value through a variable. Naming is what makes that principle useful: poorly named variables create as much confusion as hard-coded values.

Before approving a variable

I run every new name through five questions:

1. Does it clearly say what the variable is for, or what it is?
2. Does it stay true if the value changes?
3. Does it stay true in every mode?
4. Is there already a variable that does the same thing?
5. Can a developer write it as is in the code?

If even one answer is no, I look for another name before going any further.

In short

By hue when the palette is short and there's a single theme. By role as soon as an intent needs to take several values. Both, in two tiers, when the product grows, with only one tier visible in mockups. And in every case, names that describe what doesn't change, written in the words the code uses.