Design Tokens in Bricks, Explained Like You’re New

Here is an afternoon that has happened to almost everyone who builds websites. A client emails: "we've refreshed our brand. The blue is now teal." Simple, right? Except that blue isn't stored anywhere central. It's pasted into headings, buttons, icons, borders, and hover states. The same hex code, hand-typed in forty different places. You spend the afternoon hunting hex codes, and you will still miss two.

Design tokens exist so that afternoon never happens again. The idea is small enough to explain in a paragraph and useful enough to change how you build everything after today.

What's actually wrong with hardcoded values?

A hardcoded value is a raw number or color typed directly where it's used: #2563eb in a button's background, 24px in a heading's margin. Nothing is wrong with any single one of them. The problem is repetition without connection: the forty copies of your blue don't know about each other. Change one and the other thirty-nine sit there, unchanged, waiting to embarrass you.

Hardcoding also makes consistency drift. Was that gap 23px or 24px? Was the light gray #f5f5f5 or #f6f6f6? When every value is typed fresh from memory, small differences creep in, and the site slowly stops looking like one person designed it.

The fix: give your values names

A CSS variable is a named container for a value. You define it once, then refer to it by name everywhere else. It works like the contacts app on your phone: you save a number once under "Mom," and every call goes through the name. When the number changes, you update the contact, not your memory of every place you ever dialed it.

:root {
  --primary: #1b6ef3;  /* defined once */
}

.button {
  background: var(--primary);  /* used here */
}

.icon {
  color: var(--primary);  /* and here, same source */
}

Whether you write this CSS by hand or click it together in the Bricks Style Manager, the mechanism is identical: one definition, many uses. When the brand turns teal, you change one line and every button, icon, and border follows. The afternoon of hex hunting becomes thirty seconds.

So what is a "design token"?

A design token is a design decision stored as a named value. "Our primary color is this blue" is a decision; --primary is the token holding it. Your colors, your spacing steps, your font sizes: each one a decision, each one stored once under a name. The collection of all of them is, in a very practical sense, your design system: the site's entire look, listed in one place, editable in one place.

If the terminology feels fuzzy: the token is the decision, the CSS variable is how it's stored. In day-to-day Bricks work the two words point at the same thing, and nobody will mind if you use them interchangeably.

Primitive vs semantic: the one naming rule to learn

There are two ways to name a token. You can name it after what it looks like (orange-500) or after what it's for (--primary). The first kind is called primitive, the second semantic, and you don't need to remember either word. You only need the recommendation: beginners should name by role.

Here's why. Suppose the brand changes from orange to green. A token named orange-500 now holds green. The name has become a lie you'll trip over for years. A token named --primary stays honest no matter what color sits inside it, because the role didn't change, only the value. Big frameworks maintain both layers for good reasons, but a role-named set is simpler, and it's enough.

What should your first tokens be?

Resist the urge to create forty tokens on day one. A small set covers most of a real site:

• Four to six color roles. For example: --primary (brand and action color), --text, --text-muted (secondary text), --surface (card and section backgrounds), --border, and maybe an --accent.
• A spacing scale. A short menu of gap sizes, something like small, medium, large, extra large. The point is to pick from the menu instead of inventing a new number every time two things need space between them.
• Three or four font sizes. Body text, a small size for captions, and one or two heading sizes. Most pages genuinely need no more.

Since the 2.2 Style Manager, all of this lives natively in Bricks: no plugin, no extra purchase. If you later want a bigger, professionally designed system with utility classes and a full scale already worked out, that's exactly what CSS frameworks sell; our plain-English framework comparison covers when that upgrade is worth it. Everything you learn with native tokens transfers directly.

Why AI makes tokens matter more, not less

You might think AI generation makes this bookkeeping obsolete. The opposite is true. When we tested the native AI in Bricks 2.4, the generated section contained not a single CSS variable. Every color was a hardcoded hex value, statistically likely defaults with no connection to the site. Each AI-generated section becomes its own little island of hardcoded values, and you're back to hex hunting, just faster.

Tokens only pay off if new work actually uses them. That's the principle Bricksfusion Studio is built on: it generates sections against your variables, so what the AI produces is connected to your system from the first second and follows along when a token changes.

Bottom line

Every value you hardcode today is a small loan you'll repay during the next redesign, with interest. Define a handful of named values: color roles, a spacing menu, a few font sizes. Spend them everywhere. It costs you an hour of setup in the Bricks Style Manager and repays you every time anything about the design changes. Which, as every client will teach you, is always.