Variables as a system

You have your site, your team says, “Love the site. Can we change the brand color? And...  can we add a dark mode?” If you have colors set by hand, in different classes, all over the site? That’s a LONG afternoon. If you’ve built a variable SYSTEM? That’s only a couple of clicks.

This lesson doesn’t cover the basics of variables so... if you’re new to variables, we have a video that covers the basics at University dot Webflow dot com. So, be sure to check that out if you haven’t already.

What we will cover in this lesson, is how to create primitive and semantic variables, we’ll cover how to use them in Modes, we’ll talk about size and fonts, and in the end, we’ll see how a well-structured setup makes it easier for AI tools like Claude to build with you.

First, let’s set up our variables, or design tokens (as they are sometimes referred to), and we’ll start with primitives. A primitive variable stores a raw value, named to describe that value. No job. No context.

To save some time, we’ve already set up our "Primitives" collection (we called it Base collection) with blue and grey swatch scales, numbered 100 through 900 (where lighter is lower and darker is higher), using a consistent color format throughout. This is just the collection WE created but you can use whatever system makes sense for you and your team. But, Primitives are named for how they look, not what they're for. That comes next.

So... why not just use these everywhere? Good question. That’s layer two? Whoops. Sorry.

That’s layer two.

SEMANTICS. A semantic variable is named for its JOB. Not how it looks, but what it does. Think of it this way. If I name something "Blue" and the client rebrands to green? Now you have a variable called Blue... that's green. Instead, we can keep Blue as an available color and use a semantic variable to decide where it belongs.

So let's create a new collection called "Semantics." We’re separating our primitive and semantic variables into two collections here. Your team might organize collections by purpose instead, like theme colors, typography, or spacing.

BUT we’ll add a new variable: "Button Primary Background." Element, variation, then property. It reads like a sentence. And that’s what we mean by a SEMANTIC variable. Its name tells us how it should be used. The color can change, but its job stays the same.

But here's the key. I don't pick a color. I point this variable at Blue 500. That reference is called an alias. Then, we’ll head over to our design and I'll select the Button class, and in the right panel I’ll apply our new variable to the background. So the chain goes: the Button class, to the semantic variable, to the primitive.

Now, with the power of editing, I’ve gone ahead and created a semantic variable called "Link Text" that points to Blue 500, and applied it to our link styles. If we click on a link with the link styles class we can see it. Same color. Different jobs.

And here’s how it works in practice. Watch what happens when we need to make changes to the brand color. We'll go back to our Primitives (we’ll find our primitives in our variables tab), and add a new one, select color: Green 500 and choose quickly choose a green. Then, in Semantics (over on the left), I'll open Button Primary Background and point it at Green 500 instead... One change. And every element that uses this variable? Updated. No hunting through classes.

Our links stay blue. Changing Blue 500 itself would affect both. The semantic variables let us change the buttons independently. So when you’re deciding whether to share a variable, think about what should change together, not just what happens to have the same value today.

Now let’s talk about MODES. Let’s say we get a dark mode request. MODES let ONE variable hold different values for different contexts, like light and dark or across different breakpoints. Again, just to save some time, I’ve already added Surface and Text as semantics (you can see them here) and connected them to styles on our site. Right now, in Base mode, Surface points to Gray 100, and Text points to Gray 900. 

In our Semantics collection, we'll add a Dark mode up here in the right corner. In the popup modal, choose Manual since we want to apply the theme ourselves. Then, for each semantic variable, we pick a different primitive. Surface goes from Gray 100 to Gray 900. Text flips the other way. And now, when we switch modes (we select the Body, underneath the Selector dropdown in the Style panel, and we can choose Dark)... see that? Neither did I. But if we scroll down and take a look at this section, we can see the change. I didn't touch a single class. The classes still point to the same semantic variables. The values just changed. And just like that, the site's connected styles have gone to the dark mode. Colors that aren’t connected to these variables won’t change with them. But if we keep going, this is how you build the themes. We won’t cover adding a toggle for visitors in this lesson but that is a common feature.

One tip. Modes are for values that change with context, like themes or breakpoints. Modes assigned to breakpoints apply automatically at those breakpoints.. Theme modes you have to apply yourself. If a value never changes? You don't need a mode.

Which moves us to our next step. Size and Fonts. What we just showed works for more than color. Let's try size. We'll create a primitive, select Size, and we’ll call it Spacing M, with a value of Xrem, then a semantic called "Card Padding" that points to it, and apply it to the Card class. We’re moving pretty quickly but to sum that up, we’re doing the same thing we did with colors. We have our class, that points to our semantic variable that points to our primitive variable. A primitive for the raw value, and a semantic for the job. 

Now let's do fonts. Create another primitive called Font Sans for our Font Family, and a another semantic that we’ll call "Heading Font" that points to it. (We’re just choosing our primitive here.) Now color, spacing, and type are all working together from ONE system. There are other variable types you can explore here, like percentages for things like widths or opacities, and numbers for things like column counts or font weights. Again, visit Webflow University for more info on Variables.

Now for our last step. Using our variables with AI tools. A clean system is easier for people to read. And that includes AI agents... I guess... if you count them as people. Which I do, and that’s why I always tell them thank you and please. Because... well, the future.

BUT, naming consistency helps. Here, Claude is connected to our site. (That means Claude can read our variables through the Webflow MCP.) I'll ask it to look at our variables and tell me what each one is for. And be sure to check the interpretations, if they don’t match, we can always provide feedback.

Now, let's ask it to build something. A new card, using our existing variables. I’ll ask it to use our semantic variables for the background, text, padding, and heading font, and show me which ones it plans to use before building. First, I'll review the plan, (I think everything looks good here) then approve it. And here's the result.

Now, let’s select the card and inspect its styles. Are they connected to the variables we asked for? Did Claude create duplicate variables or use hard-coded values instead? And when we apply our Dark mode, do the connected colors change as expected? Not every experience is the same when working with AI tools so always be sure to check it’s work.

So if you want Claude to follow your system? Give it one it can follow. Primitive variables named for their values. Semantic variables named for their jobs. Everything organized consistently. And always review what it builds. Because a variable named "Color 7" isn't super clear for your team... or Claude.

But that's the system. We covered primitive and semantic variables, we covered modes by switching from light to dark mode, we talked a little about size and fonts, and we wrapped it up by testing our system with Claude. We made it so clear and organized that collaborating with people AND AI agents is a breeze.

But that’s creating a Variable System in Webflow.