Design Token Naming Conventions

WHY IT EXISTS As design systems grow, raw values like hex codes and pixel numbers scatter across code and design files, making global change risky. Naming conventions exist to give every design decision a stable, meaningful identity so it can be reused, themed, and refactored without hunting for magic numbers.

THE MENTAL MODEL Think of token names as a path from general to specific. A common pattern moves through tiers: a category like color or space, a semantic role like text or background, an optional component or item, and finally a variant or state like primary, hover, or disabled. The name describes intent, answering what is this for rather than what does it look like.

HOW IT WORKS Tokens are usually layered. Primitive or global tokens hold raw values, such as a palette of greys and blues. Semantic or alias tokens point at primitives and carry meaning, like color-text-default referencing grey-900. Component tokens reference semantics, like button-background-primary. A build tool then transforms this structured naming into CSS variables, iOS, or Android outputs. Because names are consistent, transformation and theming become mechanical.

WHEN IT MATTERS Naming discipline pays off at scale: multi-brand theming, dark mode, multiple platforms, and large teams. It matters most when you need to change a value everywhere at once or when new contributors must understand intent without reading docs. For a tiny single-theme site, lighter conventions are fine.

ONE CONCRETE EXAMPLE Instead of writing color blue-500 directly on a button, you define a primitive color-blue-500, a semantic color-action-default that aliases it, and a component token button-bg-primary that aliases the semantic one. To launch a new brand, you only repoint the semantic layer; primitives and component names stay untouched, and every button updates automatically.