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):
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.
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.
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.
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.
Paraphrasing Luis:
Semantic variables describe the intention, or how you want to use, primitive variables. "Red-500" might feed into "background-danger."
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.
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:
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:
So I might have collections like
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.
If you'd like to be notified of when I publish a new blog post, joining my newsletter is a great way to keep up. My readers enjoy bonus behind-the-scenes insights on every post!
