Design token changes and impact on versioning

[blackfalcon]

Problem

When using design tokens in a web or native app scenario, given that the design tokens are distributed via npm and versioned using SemVer, if an existing token changes its value, is that considered a performance update, feature update or breaking change?

Additionally, what if the value change is subtle, e.g., going from a light gray to a slightly darker gray?

Recommendation

When changing the value of an existing design token, even if the change is subtle (e.g., adjusting a light gray to a slightly darker gray), it is recommended to treat this as a breaking change. Subtle visual adjustments can impact design and user experience in significant ways, such as affecting readability, accessibility, visual balance, and brand consistency. To ensure consumers of the design tokens are adequately informed and can adjust their implementations, incrementing the major version number is advised.

This cautious approach aligns with Semantic Versioning principles, emphasizing the importance of communicating any potential impact through a major version update.

According to Semantic Versioning (SemVer) principles:

• Major version: incremented for breaking changes,
• Minor version: incremented for new features that are backward-compatible,
• Patch version: incremented for backward-compatible bug fixes.

Since changing an existing token's value has the possibility to break the existing implementation, it should warrant a major version increment to signal to consumers that they need to review and possibly update their usage of the design tokens.

Expected Outcomes

• Clear Communication: Consumers are informed of potential impacts and can take necessary actions.
• Consistency and Reliability: Maintains design consistency and reliability across projects.
• Proactive Prevention: Minimizes risk of unexpected issues in applications.
• Enhanced User Experience: Safeguards user interface against subtle negative changes.
• Best Practices Alignment: Adheres to Semantic Versioning principles, fostering trust and clarity.

[arrenleung]

I agree that changing a token's value should be considered as a breaking change. Just as an example, the new token value for --ds-color-icon-accent-default changed all auro-icon components using the accent attribute, resulting in a few unwanted changes on flight results:

Because of this, I think that we should also account for components that utilize attributes for color options (auro-icon, auro-badge, auro-button, etc.) in addition to using major version increments for design tokens.

[Patrick-Daly-AA]

I really like this mentality; Breaking design should be treated similarly to breaking functionality.

[blackfalcon]

Feedback from the phone meeting was positive and in favor of the recommendation put forth in this Discussion.

What does need to be taken into account is that any and all BREAKING CHANGES are not to be taken lightly and happen multiple times a year. Please see this other Discussion regarding the cadence of releasing BREAKING CHANGES https://github.com/orgs/AlaskaAirlines/discussions/565