Token Naming Convention

Token Naming Convention is the four-part structure that turns arbitrary variable names into clear contracts between design and code. It breaks every name into category for the type of decision, role for its semantic purpose in the interface, variant for the specific flavor of that role, and state for its interactive condition. The order stays consistent: category-role-variant-state. This produces names like color-surface-brand-active or spacing-inset-tight. The convention comes from battle tested systems at Shopify, GitHub, and IBM where thousands of components depend on these names staying stable while values change. A good name tells you the intent without opening any docs. It groups related tokens together alphabetically in code editors. It prevents the slow drift that happens when every designer picks their own favorite terms for the same concept.

The system works because it separates concerns. Primitive tokens use simple scale names like color-neutral-700. Semantic tokens use the full convention to describe usage. Component tokens add one more level of specificity only when the general semantic role is intentionally broken. This hierarchy only stays maintainable when the naming convention is followed religiously across the entire set. You see this approach evolve from early systems like Salesforce Lightning in 2016 to modern setups at Stripe and Vercel where token files serve as the single source of truth.

What it is not is a free form description of visual traits. Names like dark-blue or rounded-large encode current appearance instead of lasting intent. It is not naming tokens after specific UI molecules at the semantic level. You never want color-login-button-background in your core semantic set because that ties the token to one context and destroys reusability. It is not mixing the parts in random order or using inconsistent separators. Some teams try underscores while others use camelCase. Pick one and enforce it or you create confusion at the code level. It is not putting raw values in the names. Color-FF0000 or spacing-24 never survives a brand refresh. The name must describe the decision not the current implementation.

It is not an excuse to create hundreds of tokens for every minor variation. Some teams go overboard and make radius-button-small radius-button-large radius-card-small and so on. The convention should guide you toward sensible defaults not generate new tokens for every pixel adjustment. It is not abbreviating everything into obscurity like bg-pri-hov. Those save keystrokes today and cost hours of onboarding tomorrow.

Concrete example lives in the Shopify Polaris token set from 2024. Their color tokens follow a role first pattern that maps cleanly to the four part model. Color-bg-surface-default sets page backgrounds. Color-bg-surface-secondary handles panels. Color-bg-interactive-default covers buttons and links in their resting state. Color-bg-interactive-hover shifts on mouse over. Color-text-primary contrasts against those surfaces. When Shopify introduced a new winter theme in their admin dashboard they updated the primitive color scales from bright blues to cooler tones. Because every component referenced the semantic names like color-bg-interactive the change propagated perfectly across their entire product suite without a single component code edit. Their documentation page lists these tokens with both the CSS custom property and the raw value so designers and developers stay in sync.

GitHub Primer offers another strong example. They document functional tokens with names like color-fg-default color-fg-muted color-fg-accent and color-bg-default. State variants include color-fg-accent-hover. Their theming system uses the exact same token names across light dark and high contrast modes by changing what primitive each semantic token points to. In their open source primer.style docs you can see the JSON structure that feeds their build system. One change at the primitive level updates every theme automatically. This approach let them ship the 2023 high contrast theme in record time.

A practical example you can steal starts with your most used button. Set color-interactive-primary to your brand blue from the primitive scale. Create color-interactive-primary-hover by darkening that blue 8 percent. Add color-feedback-error for destructive actions. Then the component tokens become button-color-background-default which references color-interactive-primary and button-color-background-error which references color-feedback-error. In Figma Variables you group them under Color > Interactive > Primary > Hover. Export through Tokens Studio to JSON. Style Dictionary turns that JSON into CSS custom properties and platform specific constants. The entire pipeline stays consistent because the naming convention was followed from day one. IBM Carbon pushes this further with layer-01 layer-02 layer-03 for nested surfaces plus support-error support-success for feedback colors. Their 2024 accessibility update touched 47 semantic tokens. Zero component files changed.

When to use the Token Naming Convention is any time your project will live longer than six months or will be touched by more than two people. It shines in enterprise design systems like Carbon where nested layers require precise names to prevent contrast bugs. It becomes essential the moment you add dark mode because role based names let you swap values instead of redesigning components. Apply it before you have more than 20 components in your library. The discipline prevents the explosion of one off styles that plague growing products. Use it when handing off to developers who expect CSS variables that match Figma exports exactly.

When not to use it is during rapid ideation phases or for throwaway prototypes. A landing page built in Framer for a marketing campaign does not need this level of structure. Solo freelancers building one off websites lose more time managing tokens than they save. Early stage startups still discovering their brand should stick to direct hex values until the visual language settles. Applying the convention too early creates rigid names that no longer fit when the product changes direction. A three person team iterating weekly on an MVP gains nothing from debating token names.

Bad examples illustrate the point. A team once used primary-cta-color for their main button. Six months later they needed a secondary cta on the same page. The naming fell apart. Another team created 47 different gray tokens with names like gray-1 gray-2 up to gray-47. None described usage. When accessibility requirements changed they had to audit every instance manually. The four part convention would have forced them to create color-surface-default color-surface-subtle and color-border-muted instead. Your token names form the vocabulary your team uses to discuss interface decisions. Get the convention right and those discussions become shorter and more productive.

Nail the naming convention early and your design system stays consistent through multiple product launches and brand refreshes.