Spectrum Tokens 12.x.x to Spectrum 2 migration proposal

[GarthDB]

Problem statement

Currently, Spectrum 1 data has been released in @adobe/spectrum-tokens. This data can be found in the latest npm tag (v12.25.0) and the main GitHub branch in this repo. Spectrum 2 data can be found in the beta npm tagged releases (13.0.0-beta.34) and the beta branch in this repo.

As the data is defined in these branches today, we don't have a very clear migration path from S1 to S2.

History

Initially, the plan for S2 was to release foundational changes that would impact every component (changes to colors, corner-radius, icon sizing, and corresponding spacing). Since the original work was done, more changes have been introduced to these foundations while working on S2 components. As a result, there isn't a clear migration path in the release notes of the different beta releases of the S2 tokens.

Additionally, because of some velocity differences, Spectrum Design has been working on S2 changes without the benefit of having an implementation, like Spectrum Web Components (SWC), to verify the updated S2 token values. As SWC has started exploring the implementation of these S2 changes, they have recommended some changes that would make it easier for products to migrate to these breaking changes.

Proposal

To reduce the complexity of this S1 to S2 migration, we propose gathering the foundation S2 changes and start making a smaller initial release of S2 into the main branch on this repo and the latest tag on npm.

Even though the foundational changes would be considered a breaking change, this would be a v13.0.0, which could be considered confusing because it would be a somewhat separate effort from the v13.0.0-beta releases up to this point.

To accomplish design verification of the changes in a fully interactive implementation, I have published a snapshot release of an initial pass of the S2 color changes. This is version 0.0.0-s2-foundations-colors-20240503210338 with a s2-foundations tag. Spectrum CSS and SWC have been working to test this smaller set of data. After it is verified with Spectrum Design, we will release the next set of foundational changes as a snapshot until Spectrum Design, Spectrum Engineering, and leadership have come to a consensus on what should be included in this S2 foundations work, which will then be moved to the main branch, and latest tag in npm.

Diagram

I've included a simplified diagram of the current relationship of the S1 and S2 data and the proposed S2 Foundations workflow.

---
title: Spectrum Tokens S2 Foundations Proposal
---
gitGraph TB:
    checkout main
    commit id: "c5e4e95" tag: "12.19.1"
    branch beta
    checkout beta
    commit id: "e07c49d" tag: "13.0.0-beta.33"
    commit id: "add9fa8" tag: "13.0.0-beta.34"
    checkout main
    commit id: "a04dbd3" tag: "12.24.0"
    commit id: "ca49b00" tag: "12.25.0"
    branch s2-foundations
    commit id: "8a3298b" tag: "S2 Foundations: colors"
    commit tag: "S2 Foundations: corners"
    commit tag: "S2 Foundations: icons"
    checkout main
    merge s2-foundations
    commit tag: "13.0.0"

Loading

Alternatives considered

Before we came to the idea of this smaller initial S2 stable release, the plan was to work to a larger S2 completion with a beta branch before moving the work to main. It would be a much cleaner break with S1 data. It could lead to longer-term maintenance of multiple versions while also creating a more difficult migration path for any implementation not currently testing the S2 beta releases.

Consequences or Required Actions

As a result of breaking up the S2 verification work in implementations like SWC into smaller releases, the S2 data that will go into the main/latest releases will likely diverge from what is currently in beta. As a result, implementations like Spectrum iOS and React Spectrum, which have been working with the S2 beta branch work, will need to put in some additional work to verify and adjust. It is unclear at this time how far they will diverge, and we won't know until the S2 main work is done.

Also, we would likely have more than one set of breaking changes to get closer to the S2 design work. However, this is not seen as necessarily being a negative consequence. Ideally, we would like the products and implementations to be prepared to handle smaller breaking changes, and the Spectrum Engineering team will work to provide migration guides and potentially something like codemods/fastmods to reduce the strain on product teams.

Finally, the snapshot releases currently have our design token authoring process disrupted, and Spectrum Engineering will need to work with Spectrum Design to resolve it. However, this shouldn't be disruptive to implementations or products in the short term.

[jnjosh]

From an iOS point of view, I don't think there will be huge consequences here, we're using tokens from 13.0.0-beta.28 currently but that's largely a placeholder since we know that this first round of tokens is mostly web-focused. We may update to the foundations though to have a better starting point but I don't expect any huge issue since we don't really overlap yet on components.

[Deanna-w1]

Decision: From the design team's perspective, we can move forward with overwriting S1 token data with S2 values. There are some accessibility issues that we want to address in S1 in the future but we will fix those at the implementation or product level.

DACI:

• Driver: Deanna
• Approver: Allison
• Contributors: PJ, Bushra, Lynn, Garth
• Informed: Token system users, Spectrum leadership