Design Token Naming Conventions

Design token naming conventions establish the vocabulary and structure that teams use to identify and reference design decisions. A well-crafted naming system reduces confusion, improves discoverability, and scales effectively as a design system grows. Poor naming conventions lead to inconsistent usage, duplicate tokens, and maintenance headaches that compound over time.

What Are Design Token Naming Conventions

Design token naming conventions are standardized rules for constructing token names. These conventions typically follow a hierarchical structure that encodes information about the token’s category, variant, state, and context. For example, a token named color-background-primary-hover communicates its type (color), usage context (background), hierarchy (primary), and state (hover).

The goal of naming conventions extends beyond simple identification. Names serve as documentation, conveying the intended use case without requiring developers to look up definitions. A well-named token prevents misuse by making its purpose immediately apparent.

How Design Token Naming Conventions Work

Most naming conventions follow a structured format that progresses from general to specific. This approach creates a natural grouping when tokens are sorted alphabetically or displayed in tooling interfaces.

A common pattern uses the format: [category]-[type]-[item]-[variant]-[state]. Under this system, a token might be named color-text-primary-inverse or spacing-padding-medium. Each segment narrows the scope, making it possible to predict related token names based on partial knowledge.

The category segment identifies the fundamental design attribute such as color, spacing, typography, or elevation. The type segment describes how that attribute applies, distinguishing between background colors and text colors, or padding and margin spacing. Item and variant segments add specificity for different use cases, while state segments capture interactive conditions like hover, focus, or disabled.

Delimiter choices also matter in naming conventions. Hyphens work well for CSS custom properties, while camelCase or underscores may suit JavaScript or native platform contexts. Some systems use multiple delimiters to separate semantic levels, such as color.background.primary--hover or color/background/primary/hover.

Key Considerations

• Consistency across the entire token set matters more than any particular naming style
• Names should be platform-agnostic when tokens target multiple outputs
• Abbreviations should be avoided unless universally understood within the organization
• Token names should describe the purpose, not the value they contain
• Semantic tokens benefit from names that describe use case rather than appearance
• Name length should balance clarity with practical typing considerations
• Reserved words in target platforms should be avoided to prevent conflicts
• Versioning prefixes may be necessary during major migration periods

Common Questions

How long should token names be?

Token names should be long enough to convey meaning but short enough for practical use. Generally, three to five segments provide sufficient specificity without becoming unwieldy. Names like color-background-primary strike a good balance, while color-background-surface-container-elevated-primary-default may indicate over-specification that could be simplified.

The right length depends on the token vocabulary size and the complexity of the design system. A small system with limited color variations needs less specificity than an enterprise system supporting multiple brands and themes. When names consistently exceed four or five segments, the taxonomy may benefit from restructuring.

Should semantic tokens include component names?

Including component names in semantic tokens creates tight coupling between tokens and components, which can limit reuse and complicate refactoring. A token named button-background-primary cannot easily apply to other components with similar styling needs.

A preferred approach defines tokens by their semantic role without component references. A token named color-background-interactive-primary can apply to buttons, links, and other interactive elements. Component-level tokens, when necessary, should reference semantic tokens rather than defining values directly, maintaining a clean separation of concerns.

How do naming conventions differ across platforms?

Web platforms typically use kebab-case with CSS custom properties, such as --color-background-primary. iOS development often follows camelCase conventions like colorBackgroundPrimary, while Android may use underscores as in color_background_primary. These differences reflect platform idioms and technical constraints.

Style Dictionary and similar token transformation tools handle these conversions automatically when configured properly. The source token definition uses a canonical format, and platform-specific outputs receive appropriately formatted names. This approach maintains naming consistency at the conceptual level while respecting platform conventions.

Summary

Design token naming conventions provide the foundation for a maintainable and scalable token architecture. Effective conventions follow a hierarchical structure from general to specific, use consistent delimiters, and prioritize semantic meaning over implementation details. Organizations that invest in thoughtful naming conventions reduce confusion, improve onboarding, and create token systems that remain coherent as they grow.