Design Tokens 101: The Foundation B2B Design Systems Get Wrong

Teams that build a design system often stop at components: buttons, cards, inputs, documented and reusable. What gets less attention is the layer underneath the components, tokens, and it's usually what breaks first once a B2B product needs a second brand, a dark theme, or a white-label deployment.

Design tokens are the named values, colors, spacing, type sizes, that a design system references instead of hard-coded numbers, so a single change propagates everywhere it's used. B2B design systems tend to get tokens wrong in one of two ways: they skip the semantic layer and reference raw values directly, or they name tokens after their current value instead of their purpose, which breaks the first time a rebrand, a dark theme, or a white-label client relationship needs a different value behind the same name. Getting the token layer right is what lets a design system survive change.

Three tiers, not one flat list

Design tokens work in three tiers. Primitive, or reference tokens hold raw values, including a hex code, a pixel amount, and a font weight. Semantic tokens give those primitives a purpose, such as color.text.muted or space.compact. Component tokens map a semantic token to a specific piece of UI, like button.background.primary. Flattening this into one list, naming everything after its raw value, is the single most common structural mistake in B2B token systems.

The tiers exist so a decision only has to be made once and at the right level. A brand color change is a primitive-tier edit. A decision about what success looks like across the product is a semantic-tier edit. A one-off exception for a single component is a component-tier edit, made deliberately.

Our breakdown of product design for SaaS covers what a design system needs to do as a whole, components, patterns, and tokens together, to hold up as a product scales. This piece stays focused one level deeper, on the token layer alone, because it's the layer B2B teams tend to build last and get wrong first. For the fuller picture of design systems generally, our design systems guide covers the broader structure.

Naming tokens after their current value is the mistake that costs the most later

A token named color.blue.500 or sizing.border.2 describes what the value happens to be today. While that's fine at the primitive tier, where raw values are supposed to look like values, it becomes expensive at the semantic tier, where a name is supposed to survive the next redesign.

The fix is naming tokens for the role they play, color.text.muted instead of color.text.gray, so a value can change without the name lying about what it now means. This is one of the most common and costly naming mistakes teams make when building token systems, and it's rarely caught until the first rebrand or theme change forces a rename across every file, codebase, and doc that referenced the old value.

B2B products hit this specifically at white-label and multi-brand moments

A consumer product usually has one brand, one theme, and no reason to interrogate its token architecture until a redesign. A B2B product frequently needs to support a white-label deployment, a dark theme, or a second brand after an acquisition, and that's when a flat, value-named token system falls apart.

If a token is named green.500 and a white-label client wants their brand's colors, that token can't be safely repointed to a different hex value, since every place it's used still says "green" in the name while displaying something else entirely. A semantic name, color.action.primary, doesn't have this problem, because the name isn't claiming to be a specific color. This is a B2B-specific failure mode that most general design-token guidance, written with a single consumer brand in mind, doesn't account for.

Renaming a token without a migration plan is a breaking change

Every consumer of a token, design files, application code, documentation, tests, has to update when a token's name changes, even when the new name is objectively better. Deleting the old token and announcing the change in release notes is a guarantee that something downstream breaks quietly.

A safer sequence adds the new token, aliases the old name to it, marks the old name deprecated, measures remaining usage, and only removes the alias once consumers have actually migrated. That sequence costs more time upfront than a straight rename, and it's the difference between a token system teams trust and one they route around.

Get the token layer right the first time

A component library built on a flat, value-named token system looks fine until the first rebrand, dark theme, or white-label request. At BRIGHTSCOUT, our app development team builds the token architecture underneath a design system, not just the components on top of it.

Let's talk about what your product needs.