The Anatomy of Design Tokens

Token 3.0 naming and tiers

Introducing Token 3.0 Naming and Tiers

We're excited to unveil style-tokens 3.0, which brings a fresh approach to token naming and introduces the concept of 'tiers' for clearer communication of our design structure.

Token Naming Convention

All tokens now adhere to a structured naming convention that simplifies their identification. The format appears as follows:

• Tier* / Category* / Property / Concept / Sub-concept / Item / Sub-item / Variant / Scale / State

Note: Tier and category are marked with a * because they are essential components in every token name, while the other elements are included as needed, becoming increasingly relevant as the specificity of the token grows.

Examples:

In JSON:

• p.color.brand.500
• s.size.line-height.heading.xlarge.mobile

In CSS:

• --p-color-brand-500
• --s-size-line-height-heading-xlarge-mobile

Understanding Token Tiers

We've categorized tokens into four tiers: Primitive (P), Base (B), Semantic (S), and Component (C).

The order of these tiers is crucial:

1. Primitive -> 2. Base -> 3. Semantic -> 4. Component

This sequence is significant because tokens inherit values exclusively from the preceding tier.

Illustration

For instance, if we have a color token hierarchy like this:

1. #CE0303 (Value)
2. p.color.brand.500 (Primitive tier token)
3. b.color.primary (Base tier token)
4. s.color.background.brand (Semantic tier token)
5. c.color.background.button (Component tier token)

The "Component" tier is reserved for exceptional situations where precise control over a component-level value is necessary.

We hope this simplified naming scheme and tier structure will enhance your understanding and usage of our style tokens in design and development. If you have any questions or need further clarification, please feel free to reach out.

Tier explanations

The Anchor ⚓️ Design Tokens are oranized into these distinct tiers – Primitive, Base, Semantic, and Component – where we establish a clear hierarchy that fosters consistency, scalability, and maintainability across the Anchor 3.0 design system. This structured approach empowers frontend developers with the flexibility to choose the appropriate level of abstraction for their specific needs while maintaining a cohesive and well-defined design language.

Semantic (S) 📝

If you are a frontend developer, you will likely spend most of your time working with Semantic tokens. Please use the Semantic tokens as much as possible to ensure consistency and maintainability across the design system. And make sure that you are using the right token for the right property.

The Semantic tier introduces tokens defined by their intended usage, providing a semantic and context-specific naming convention. Here, you will find tokens tailored for properties such as "background," "border," "text," "lineheight," and more. Semantic tokens can reference both Base and Primitive tokens, allowing for a structured and purposeful extension of design elements. By incorporating semantic naming, this tier enhances the readability and comprehension of design decisions for frontend developers.

Base (B) 🛠️

In the Base tier, we define general-purpose tokens that maintain a level of agnostic naming, ensuring versatility across various design elements. Base tokens directly reference Primitive tokens, inheriting their foundational values. This tier establishes a standardized set of values for commonly used properties, fostering a cohesive visual language. Base tokens act as a bridge between the raw values in Primitive and the more semantically meaningful tokens in higher tiers.

Primitive (P) ⚙️

The Primitive tier serves as the foundational layer where fundamental values are defined. These tokens are not intended for direct application within user interfaces but act as building blocks for higher tiers. Developers will use Primitive tokens to establish the core values upon which Base, Semantic, and Component tokens are constructed. These tokens provide a level of abstraction that promotes consistency and modularity throughout the design system.

Component (C) 🧩

The Component tier is reserved for tokens specifically crafted to meet the granular requirements of individual components within Anchor ⚓️. These tokens are to be used exclusively within Anchor components, ensuring precise control and customization without impacting the broader design system. The Component tier minimizes redundancy by providing component-specific tokens, enhancing modularity and encapsulation within the design system. It is crucial to keep the usage of Component tokens to a minimum, maintaining simplicity and efficiency in component-level styling.