Design Token Naming Conventions for Multi-Brand Systems

A design token is a design decision, color, spacing, type size, corner radius, stored as named data and distributed to every platform a product ships on. The name attached to that data makes a brand's visual rules swappable, versionable, and reliably consumable, or forces every rebrand, every new brand added to a portfolio, and every dark-mode variant into a manual migration across design files and codebases.

The idea traces back to Salesforce, where the Lightning Design System team needed the same visual decisions to reach web, iOS, Android, and partner platforms without re-typing values by hand, in the team's own words, "a way to store our visual information as data." That origin matters because it clarifies what a token actually is. A CSS custom property, a Figma variable, and a Swift constant are each a single platform's implementation of a token, not the token itself. The token lives in a data file, upstream of all of them, and gets transformed into whatever format each platform needs.

Names carry the weight of that translation. When they're inconsistent or unclear, designers and engineers hesitate to use the tokens that already exist, can't find what they're looking for, don't trust what they do find, and build duplicates instead. That's a governance risk, because duplicated tokens fragment the system slowly, and over months nobody can be sure which token is canonical. The common defense, that a team can always rename later, collapses under its own timing: renaming a token after components and code have already consumed it means touching every reference simultaneously, across every design file and every repository that pulls from it. The cost of a bad name grows with adoption, not before it.

Get naming right at the outset and the economics invert. A rebrand becomes a matter of repointing a handful of aliases to new values. Dark mode just becomes a second set of mappings, not a second design system. Adding a new brand becomes an operation measured in hours of configuration.

What the three tiers are responsible for

The structural pattern that makes this possible is the three-tier model: primitive, semantic, and component. Each tier owns one kind of decision, and the discipline comes from refusing to let raw values, intent, and component-specific overrides blur into one another.

Primitive tokens (also called reference, global, core, base, options, or foundation tokens, depending on the system) hold raw, unopinionated values: hex codes, pixel sizes, millisecond durations. A primitive answers the question "what values exist," never "where do they go." This is the one tier where a name is allowed to describe a value directly, something like blue.500 or space.4. Primitives are meant to be immutable and global, the foundation everything else draws from. Components should never consume them directly.

Semantic tokens (sometimes called alias, system, or theme tokens) map those primitives onto contextual roles and carry intent. A token like color.action.primary might resolve to {blue.600}, but color.text.danger carries its own meaning regardless of which primitive backs it. Semantic tokens answer "what does this value mean," not "what is its value," and this is the tier where theming lives. Dark mode and brand switching both happen here: a second set of semantic mappings points at different primitives, and no component downstream needs to know the difference.

Component tokens scope a decision to a single component, something like button.primary.background: {color.action.primary}, letting one team restyle one button without touching the shared vocabulary everyone else depends on. Component tokens should always reference semantic tokens, never primitives directly. That layer of indirection is what keeps the whole system flexible.

If you follow one color decision through all three tiers, the logic gets concrete. A primitive, blue.600, is just a value. A semantic token, color.action.primary, assigns that value the role of "the color our primary actions use." A component token, button.primary.background, pins that role to one specific part of the interface. Material Design 3 runs this exact cascade in public: md.ref palette tokens feed md.sys system tokens, which in turn feed md.comp component tokens, and it's the most complete free worked example of the pattern you can study.

The dependency flow only runs one way: primitive to semantic to component. Reverse references, or mutations that cross layers, introduce circular dependencies that undermine build-time optimization and make runtime behavior unpredictable. The tiers only function as a system when the direction of reference is treated as a hard rule, not a convention.

The one naming rule that decides whether tokens survive a rebrand

Every naming decision inside that three-tier structure reduces to one rule: name tokens by purpose, never by value. A token called red-dark states a fact about today's design. A token called color.text.danger states a decision, one that survives every rebrand, every new theme, and every dark-mode variant that comes after it.

The failure mode of value-based naming is simple to see once named. A token called color-green-button records that the button is green, so when the button's color changes, every place that token is used is now reading a name that contradicts the value it resolves to. A purpose-based name doesn't have this problem. When one brand decides to render its success state in amber instead of green, or when dark mode flips a surface from light to dark, color.text.danger keeps its name and only its underlying reference changes. The name is a description of a role in the interface, not a description of a hex code.

That purpose-first discipline is visible in how a full token name is built. Reading left to right, the anatomy runs: a namespace identifying the system (acme-, spectrum-), a category naming the output type (color, spacing, font), a concept grouping it semantically (background, action, feedback), a property naming the CSS target (text, border, fill), a variant marking its position on a scale (primary, secondary, lg), and a state capturing interaction (default, hover, disabled, focus). The order is positional and never gets reshuffled, because a name that reads consistently from owner to category to role to variant to state can be parsed by a linter, grouped automatically in documentation, and diffed between releases without anyone consulting a lookup table.

Delimiters carry their own discipline. In the source file, groups nest as JSON objects, color containing text containing default, because that is how the W3C token format structures hierarchy. You reference a token across that hierarchy with the curly-brace alias syntax, and it uses dots, {color.text.default}. The CSS custom properties a build system emits use hyphens, --ds-color-text-default. A single namespace prefix on that CSS layer keeps a brand's tokens from colliding with some third-party stylesheet loaded on the same page.

None of this works if the underlying intent is muddy. A token name has to be short, meaningful, easy to understand, modular, and consistent, because the moment intent is unclear, every team applying that token is making its own local judgment call, and those calls accumulate into exactly the inconsistency the system was built to prevent.

How the tier model makes multi-brand systems maintainable

This is where the tier model earns its keep. In a system supporting multiple brands, the three tiers mean you maintain one shared component layer sitting on top of brand-specific semantic and primitive layers, instead of building a separate design system for each brand from scratch.

The mechanism is a consistent alias held across every brand. A token like color.brand.primary exists once, by name, across the whole portfolio, and brand-specific values live in separate token sets that remap that alias to different primitives. Brand A might resolve color.brand.primary to color.blue.500. Brand B resolves the identical alias, color.brand.primary, to color.green.600. You write the component consuming that token once, and it never changes between brands, because only the token set applied at runtime differs. That's the entire mechanism, and it's why a shared component library and genuine brand differentiation aren't in tension.

Theming compounds along more than one dimension at once. Color mode, brand, density, and platform all compose orthogonally, so a "dark plus partner-A plus compact" theme is really three independent token sets layered together, applied through multiple data attributes or composed CSS classes, something like [data-mode="dark"][data-brand="partner-a"][data-density="compact"]. That kind of composition needs runtime CSS variables rather than values inlined at build time, because the combination of mode, brand, and density isn't knowable until the page actually renders. Platform differences follow the same logic rather than forking into separate token trees: naming gets extended with platform context where it's genuinely needed, elevation-medium-ios alongside elevation-medium-web, instead of letting one-off platform values leak into the global vocabulary.

The failure mode at scale tends to be namespace collision. A flat namespace shared across brands will collide the moment two brand themes get merged at runtime, and the fix is to give each brand its own namespace at the semantic layer, --brand-a- and --brand-b- as distinct prefixes. Conway's Law applies directly here: an organization split into siloed teams will produce token names that are just as disjointed and fragmented as its org chart, scattered inconsistently across platforms. The structural fix is organizational as much as technical: you run cross-functional workshops where designers and developers co-author the token names together, so the naming vocabulary reflects one shared mental model.

When to introduce the third tier

None of this is an argument for maximal structure everywhere. Adding the component tier before multiple teams are actually shipping against the same shared components adds more overhead than it removes. Two tiers, primitive and semantic, is a complete, functioning system on its own. A third tier introduced before it's needed is ceremony with a real cost attached to it.

That cost is countable. A primitive-plus-semantic vocabulary typically runs to a few hundred tokens. Layering a full component tier on top pushes that count into the thousands, and a token vocabulary that large only pays for itself if teams are actually adopting it. A component tier nobody uses fails for the same reason a component library nobody uses fails: it's maintenance surface with no corresponding benefit.

The right signal for adding component tokens is organizational. It pays off once multiple teams need to restyle the same shared component independently, without side effects on each other's work. Before that point, the third tier adds complexity but gives you no real capability. The sequence that works in practice starts with a minimal set covering color, spacing, typography, and radius, stabilizes the primitives, attaches semantic intent on top of that stable base, and only scopes component-level overrides once teams are actually asking for that degree of independent control.

Dark mode and brand switching require no component tier. Both operate entirely at the semantic layer, through remapped aliases. Adding component tokens specifically to support theming is a common overcorrection, and it inflates the token set without adding anything theming actually needs.

The toolchain that enforces naming conventions across design and code

The naming discipline described above only holds if the toolchain enforces it automatically, rather than depending on individual designers and engineers remembering the rules. That toolchain has settled around three pieces working in sequence: Figma Variables on the design side, Style Dictionary as the build step, and the W3C Design Tokens Community Group format as the interchange layer connecting them.

The W3C format, specified in the Design Tokens Format Module 2025.10, standardizes the JSON schema itself: $value, $type, $description, and $deprecated as reserved properties, with groups nested as JSON objects and the curly-brace {group.token} syntax used to walk that hierarchy when one token references another. That shared schema is what lets a design tool and a build system agree on what a token is without a custom translation layer between them.

On the design side, Figma Variables holds the actual token definitions, and plugins such as Tokens Studio extend that with grouping, aliasing, theming, multi-brand structuring, and syncing to a GitHub repository or directly into a build pipeline. Style Dictionary, originally built at Amazon and released as open source, takes that canonical token file and transforms it into whatever each platform needs: CSS custom properties, iOS and Android formats, and other platform-specific outputs, all generated from the same source.

The discipline that keeps this reliable is a strict one-directional flow. One canonical token file generates every downstream artifact. Teams that let Figma and code drift apart independently end up maintaining two separate design systems that happen to share a name, and reconciling them later costs far more than keeping the pipeline one-directional from the start. CI enforcement closes the remaining gap: running JSON schema validation in the pipeline checks naming conventions, type constraints, and resolved references before any artifact is generated at all, because a naming convention enforced only by memory and good intentions will drift the moment a team is moving fast.

Figma's Dev Mode MCP Server, announced in beta, extends this pipeline in a different direction. It lets agentic coding tools, including Cursor, Copilot in VS Code, Claude Code, and Codex by OpenAI, pull design context directly out of Figma files, rather than requiring someone to manually export specs or re-describe a design in a prompt. That bridge from design file to coding agent is what makes the final argument of this piece possible.

Well-Named Tokens as the Prerequisite for On-Brand AI Output

An AI agent generating UI code or creative output has no built-in sense of a brand's visual rules. Without a structured, machine-readable token system to read from, it guesses, and those guesses drift, from brand to brand within the same portfolio and from run to run on the same brand.

Today, an agent generating frontend code tends to infer design decisions from stray comments left in CSS files, or it skips design consistency as a consideration entirely, and what it produces is structurally functional but visually arbitrary. A machine-readable design token file changes what the agent is working from. The design system becomes a first-class input to the generation process, not an afterthought bolted on during review.

The practical version of this looks like a workflow that reads directly from the token file and builds its system prompt dynamically, rather than hardcoding brand values into a static prompt somewhere. When the brand's token set updates, whether that's a rebrand, a new seasonal theme, or a partner-brand variant, the prompt updates with it automatically, and every agent downstream inherits that change without anyone rewriting instructions by hand. The naming discipline built across the primitive, semantic, and component tiers is what makes that inheritance reliable: a purpose-named token tells a human designer and an AI agent the same thing, in the same structured format, every time it's read.