Organize your variables in 3 levels of collections

Something I so appreciated about Luis Ouriach and Jacob Miller's deep dive on variables from Config 2023 is that they pushed for standardizing a naming convention.

In the deep dive Luis called these "types" of variables, but I'm going to use the word "levels", because "type" already means something: the kind of information that the variable value contains. Types of variables include numbers, colors, strings, booleans, or images (which was promised to come in late 2023, still waiting though):

Screenshot of the 4 types of variables from Figma's help documentation on variables

I prefer "level" over "type" because a level implies a more linear relationship. And that's exactly the kind of relationship these different kind of collections have: linear. Hierarchical. These levels are named primitive, semantic, and component. I think they're strong names. But they didn't click for me at first. I was like, "semantic... what the heck?" It wasn't until Luis described the semantic level as where you "layer in intention" that the lightbulb went off for me.

If you've also been struggling with knowing what folks mean when they refer to these different levels of variable collections, this post is for you. I came up with a real-world analogy about how to think about variable levels. This could help you organize better and get your team on board with the concept if they're also struggling.

Primitives

Way before Figma put out variables, my talented colleague Jay Miles referred to color as a "raw material." How good or bad the material looks is all about how you apply it. So set aside names like "red-100", "blue-800" for a moment and imagine you're doing remodeling project in your home. You might have some raw materials to work with, like antique glass, walnut wood, brass, ceramic. You can picture what these materials look like, feel like, maybe even smell like. But they don't have a "shape"—not yet.

Example images of 4 raw materials: ceramic, brass, antique glass, walnut wood

Coming back to the digital design world, here's how primitives are described in Luis' words:

Primitives describe what the token looks like. Red-100, Red-200, Red-300, they'd be exactly that: red.

Semantic

This is where you take your raw materials and imbue them with intention. What role does our antique glass play in your remodel? 

Maybe you want to use it for accent lighting.

You can begin to picture rooms and situations where you'd see these materials, even the "shapes" they could take, but those shapes haven't been explicitly named. "Accent lighting" is still pretty broad. It take many forms. Lamp shades, sconces, track lighting, etc.

For some teams, this level of definition is as far as you need to go with your variables.

Example images of 4 intentions of the raw materials: pendant, track, sconces, and LED strips.

Paraphrasing Luis:

Semantic variables describe the intention, or how you want to use, primitive variables. "Red-500" might feed into "background-danger."

Component

This level is where you name those "shapes" you want your intentions to take.

Your accent lightning that uses antique glass—maybe you specifically want it to come to life in the form of retro looking table lamps.

Or the the brass—perhaps that's for bathroom hardware, specifically knobs, faucets, towel racks, and shelving supports. These are specific objects that will be used in specific areas of your home.

Example of 4 locations for antique glass table lamps: office, entry, bedroom, living room.

Paraphrasing Luis:

Your button component may get a variable called "button-background." But this is optional, you may not need the component level at all. Instead, you could have a "background-action" variable stored in your semantic layer. The component level of variables is useful is if you do A/B testing on components. Or if you want to test a new release of a specific component.

<div class="horizontal-rule"></div>

I also want to be clear: this does not mean you will only ever have 3 collections total. You might have 2 primitive collections, 10 semantic ones, and 24 component collections! And don't even read into those numbers, I'm pulling them out of the air.

My prediction is that as we learn to use this new feature, many people will be anxious to know the "correct" number of collections they should use. But this will be difficult to give general advice about, because it will likely depend on:

  • How mature your design system is.
  • How many products and brands you need to support.
  • The Figma plan you use.

For now, I can only confidently speak to what I'm doing. As I explore variables I've found myself using double-digital numbers as a prefix to my collection names:

  • <span class="inline-code">00</span> = Primitive
  • <span class="inline-code">01 -</span> = Semantic
  • <span class="inline-code">02 ❖</span> = Component

So I might have collections like

  • 00 Primitives
  • 01 - Color
  • 01 - Spacing
  • 01 - Breakpoints
  • 01 - Device screens
  • 01 - Validation styling (blog post about why this should be a variable collection and not a variant property)
  • 02 ❖ Spacing
  • 02 ❖ Prototyping
  • 02 ❖ Color

For now, my best advice is to find a naming system that works for you. Clearly mark what is "primitive", what is "semantic", and what is "component" (if you even use it). And if anyone asks what belongs where, send them this blog post.

Change log

  • Current version
    • Updated the introduction to mention that the variable type, "image" was promised to arrive in late 2023 but we are still waiting on it.
    • Added "01 - Validation styling" to the list of collections I use in my design system work, linked to my blog post about this collection.
  • August 15, 2023
    First published.