Compare release approaches for design system 2.0 (override file vs major version vs new library and more)

[Spark450]

Summary
Produce a comparison of options for releasing the visual/design updates (Design System 2.0). The artifact should outline benefits, drawbacks, risks, migration impacts, and recommended next steps for each approach.

Acceptance criteria

-Comparison includes at least the three baseline options plus any others identified during discovery

• Each option is evaluated against the defined criteria (impact, migration effort, risk, etc.)
• Final recommendation is clearly stated and justified

Background

We’re beginning work on the visual refresh. Three initial release approaches have been mentioned:

1. Override file (new token file layered on top of existing tokens/components)
2. Major version of the existing component library
3. New component library (v2.0)

There may be additional variants/approaches worth considering. Our UX direction needs to be informed/involved in the decision and rationale.

Problem statement

We must choose a release strategy that:

• Minimizes disruption to current users
• Scales for future visual design and functional changes
• Balances technical complexity, risk, and long-term maintenance efforts

Goals

• Document and compare each viable approach using consistent criteria
• Produce an artifact suitable for executive review (concise, outcome-focused)
• Recommend a preferred option (with rationale)

Potential Deliverables (choose 1 or more)

• Comparison matrix / brief (one-pager): Pros, cons, risks, effort, migration path, governance implications
• Technical notes (detail level): Spike results (if needed), implementation considerations, testing implications
• Executive summary deck slide(s): Clear recommendation + why now / why this approach

Evaluation criteria (use these to score each option)

• Impact on existing consumers: Breaking changes? Required code changes?
• Migration effort & tooling: Time, scripts, docs, guides required, upgrade videos
• Risk & rollback strategy: Ability to revert, isolate changes, or run in parallel
• Governance & versioning strategy: How we signal changes, maintain support timelines
• Maintenance & scalability: Long-term upkeep

Out of scope

• Implementing the chosen approach (will be tracked separately)

[Spark450]

From the intital tests the "override file" approach would not address all of the changes in 2.0 components.

[twjeffery]

@chrisolsen I been working on a process #2893 for:

1. Implementing the updated components in our Figma libraries
2. Creating a detailed handoff/spec of all changes needed for development.

I also took this a step further and have started to test out implementing these changes into our coded components -- Radio and Callout for a v2.0 and wanted to share the findings.

---

Key findings

• There are structural changes needed - new properties and layout changes are needed that go beyond just styling
• Old and new "styles" shouldn't coexist on the same page - the old/new styles for each component change dramatically, meaning that the experience would be broken if old and new versions of the components are mixed on the same page in an application.

Option 1 won't work: (override file)

• There are structural changes needed - new properties and layout changes are needed that go beyond just styling
  • Option 1 won't work - the "override file" approach would be insufficient for the property and layout changes that are needed

Option 2 benefits: (major version upgrade)

• Components can't coexist (prevents mixed styling)
• Natural forcing function (teams update for new features)
• Simpler for teams (same package, familiar process)

Option 3 benefits: (new component library)

• Opportunity to rebuild/rethink how we build our components
  • with AI-assisted development rapid execution is possible, especially building off of and learning from the current library
• Gradual migration (teams choose timing)

[chrisolsen]

Override file

Pros

• Simplest
• Allows teams to override existing token
• Allows for easy rollout at a later time

Cons

• Will result in wasted bandwidth with both design tokens being downloaded by users
• For some components it may require additional logic added to accommodate v1 and v2 designs ex Accordion
• Hackiest

Major version of existing component library

Pros

• Things are separate so we don't have to worry about breaking anything in the old version
• We don't have to release updates for the old version

Cons

• Maintenance nightmare. We would then have 3 versions of the library that we would have to maintain.
• With another major release would result in the current version being put into LTS state, which would not be liked by other teams.

New component library

Pros

• If this includes the shift to a single lib, this would allow us to shift away from web-components and utilize some of the currently missing features

Cons

• Maintenance nightmare in porting bug fixes to both versions
• Current version is moved to LTS.
• More tests that have to be performed
• Hard to make any later changes if the direction changes in the future.
• Another lib we have to support, since we still have to support the old components.
• Unless teams are mandated to use the new lang of choice, teams would shift back to using other open source libs.

Experimental components

Components would be created in an experimental (or something of the like), folder.
- could contain a console.warn message to help prevent people using them not realizing they are experimental. Could provide a prop to disable the warning.

Pros

• Don't have to fully rewrite every component
• No longer need to manage multiple versions
• Component specific tokens could be defined within the experimental component, allowing for easy override of the current (v1) tokens.

Cons

• Some components will need to be imported differently

[ArakTaiRoth]

Override File + Experimental Components

Can only really be done if combined with the Experimental Components option. This is because there's more than just visual changes to these components, but not all components require more than that. So the visual changes only would be done via an Override File, and the functional changes could be done on a component by component basis.

Pros

• Allows an easier way to upgrade - gives complete freedom of choice on what to upgrade
  • People who want the visual changes need only apply the new Design Tokens
  • People who want the functional changes just need to switch to whatever experimental component they want
• Potentially the easiest option, requires mostly only changes to Design Tokens and creating a new version of Design Tokens
• Considering Design Tokens as they stand now are basically not changing any longer, this is the easiest to support

Cons

• Would still require maintaining bug fixes on two separate versions for some components
• Would have to decide where we add new features to these components, do we add them for "old" components and new experimental components or only one of them?
• Eventually the goal would be to make the experimental components the default components I believe, would have to decide when that is and communicate that effectively, because that will effectively lock people out of updating unless they want a redesign

Major Version Update

The biggest issue with this is telling people "hey, you know the version you just spent the last 6 months updating to, now it's out of date and you need to update again". Also has an issue with new features, assuming we only add new features to the newest version, then teams have to accept a whole app redesign in order to access any new features they may want. In addition, then we need to support the LTS version for at least a further 6 months, and with the changes being made to web-components and not react-components, that support would look decidedly more complicated and time consuming than our last try at supporting an LTS version. Keep in mind we get comments if margin is changed on a component, can you imagine the comments if their whole app changes it's entire design?

Pros

• I honestly can't think of a pro here, this would be a nightmare to communicate to people and get them wanting to update, essentially I don't think anyone would update unless they were starting a brand new project and had these designs to work with from the get go, and because of that would be a maintenance nightmare because we would essentially have to provide bug fixes for 2 versions for every single bug story for a very long time.

Pros

• Simple for teams to upgrade, if they decide they want to. Essentially no code changes, just design changes, and effectively nothing they have to do on their end other than just change version numbers.

Cons

• We can remove the issue of supporting 3 different versions by just delaying this update until after September, then we only have to deal with 2 versions. But the amount of support required because it's web-components would be magnitudes larger than the last support we had to offer (which was only a few stories over 6 months - this would be almost every bug story)
• Essentially forcing people to accept a whole new redesign in order to get new features, I can't imagine literally anyone being happy about this.
• Doing this is essentially only an option for teams starting off new, older teams would essentially be stuck with no new features and only bug fixes

Complete New Library

This seems insane to me that we would do this. I know it's been said that "with AI we'd be so much faster", I'd like to offer a second opinion. That's not how that works, like at all, read this. Maybe I'm the only one that's seeing a ton of problems with AI written code on an almost daily basis, but it's wrong, like a lot. It is not infallible, and it's not something we just ask it to do and then it's done, no need to review, no need to fix, no need to do anything. Please do not introduce us to vibe coding (which is coding exclusively with AI, then not checking and just pushing).

Pros

• We get a chance to develop from scratch completely new components, we can do whatever we want, use new features not originally available to us, new languages, anything, the world is our oyster.

Cons

• The sheer amount of time required to do this would be hilarious. We've been building our current version of our library for the past 4 years (around there), the thought that we could replicate everything from scratch in anything less than 2 years, seems laughable to me.
• Think of all the new bugs we could create and see, it would be amazing
• Our backlog would grow immensely, because not only will we have issues with the new library, we'll still have reports of issues from the old library as well
• Have to support our old version, for how long? Anyone wanting to update will have to contend with a completely new design and likely completely new implementation, so not only would their design change, but effectively all of their code would to. This would make the cost to upgrade essentially a no go, no one would do it.
• It would take forever until we had something to offer people that would be feature complete enough that they would want to use it

[Spark450]

Based on the discovery we have a update approach outlined here