Integrating Carbon v11 styles (prereleases)

[theetrain]

Update 12 January 2024: Contribution guide
Update 19 January 2024: Fewer breaking changes in contributing guide

At a glance

• We are integrating Carbon v11 styles (based on @carbon/styles@1) one component at a time.
• As we integrate more components, we will ship unstable releases to npm under the next tag. You may try them out by installing as:

  npm install -D carbon-components-svelte@next
  

  By default, npm install carbon-components-svelte will use the latest stable tag.
• Progress is being tracked in Carbon v11 style integration (component checklist) #1629
• Contributions are welcome! See guide below.

The plan

In an effort to get us closer to carbon-components-svelte v1, we will be making pre-releases that incrementally implement Carbon v11 styles across all components. The proposed workflow being:

1. Create a next/v11-styles branch.
2. Import Carbon v11 Sass and generate respective themes as .css files
3. Make a release to npm using the next tag; with pre-release tags using the v1.0.0-next.0 convention.
4. One by one, ensure every component in carbon-components-svelte matches the visual and interactive behaviours of the flagship Carbon library; continuously making pre-releases as we confirm them.
5. Any fixes made to master during this period will be ported to the v11 branch.
6. Once we have confidence all components have their v11 styles properly applied, we will merge v11 onto master and the next release will use the v1.0.0-beta.0 convention until the v1.0.0 milestone is complete

With these releases, it will become easier to test v11 components and styles in your projects and make contributions to all yet-tested components (tracked in #1629). We aim to ship the first pre-release by early January 2024.

Contributing

Contributions are welcome! We recommend contributing one component at a time to the next/v11-styles branch during this period; let us know in the discussion here or in #1629 which component you wish to integrate.

How to contribute:

1. Send us a message in Carbon v11 style integration (component checklist) #1629 or here to let us know what you would like to contribute. You may also run the documentation locally and verify that a certain component is "v11 ready" and we can mark it as complete. Try to keep pull requests small, targeting one component directory at most.
2. Clone the repository
3. Create a branch based on next/v11-styles
4. Use npm, run npm install (see CONTRIBUTING.md)
5. When improving a component, use the React library as a reference.
   • Carbon React Storybook
   • Carbon React source
   • Focus on upgrading v11 styles only. Only change props and types such as kind if they are directly impacted by v11 styles or behaviours. We can address Standardize props, events, and slots #1621 and other tickets after v11 styles are released and stable, and before the release of [email protected]
6. Test. Ensure the component you're developing features all functionality on par with the React library. Including:
   • visual designs
   • responsive behaviour
   • interactions (test keyboard interactivity as well)
   • Works across the 4 themes; white, g10, g90, g100
   • Component works well with related components, where applicable. For example: FluidForm, Tooltip.
   • Be mindful of screen readers, screen magnifiers, and other accessibility considerations outlined by Carbon
7. Create a pull request, using next/v11-styles as the target branch

See also

• Carbon v11 style integration
• v1.0.0 Roadmap
• v1.0.0 Milestone

Tagging potentially interested folks: @eltigerchino, @gregorw, @brunnerh, @SimpleProgrammingAU

[theetrain]

First prerelease was made: v1.0.0-next.0. 👋

See updated notes above along with the contribution guide.

[theetrain]

Summary - for the remainder of this prerelease phase, we'll try to avoid breaking changes unless they directly relate to v11 styles and behaviours.

Regarding breaking changes

I'm bringing in conversations from #1889 (comment) and #1895 (review) for better visibility and posterity.

Since we only have 2 part-time volunteer maintainers working outside IBM, and the scope of carbon-components-svelte is very large, it may take a very long time to get us to v1.0.0. Releasing v11 styles incrementally is also not viable since it impacts their entire library, so this prerelease initiative was made to make it easier to solicit contributions and track changes until full component coverage is met.

We anticipate folks using these pre-releases would do so for the sake of testing, contributing, or raising concerns during this period since they are unstable and not production-ready. Though we had tried to implement Carbon v11 styles earlier in 2023, it turned out to be a larger effort than expected; and by introducing pre-releases after the initial setup made in #1881, it should be straightforward to make adjustments one component at a time now that all CSS and theming is in order.

Addressing concerns

We should focus only on the changes required to adopt v11 styles. Other changes such as #1621 should be out of scope. In turn, this should make PRs easier to review and when we v11 styles are properly released, consumers should have an easier time upgrading.

I agree in principal: breaking changes should be as few and far in between as possible for both reviewers and consumers. Though we cannot commit to "enterprise-grade" release cadences, perhaps a new approach is needed. Here are the trade-offs I see:

1. If we include Standardize props, events, and slots #1621 as part of adopting v11 styles, then there would be more breaking changes to write down for the eventual stable release of v11 styles, and more refactoring for users to contend with for a single package upgrade.
2. If we only focus on adopting v11 styles for now, without including refactors or clean-ups, then we can make a stable release of v11 styles and then follow up on these other plans before v1.0.0. There will be just as many breaking changes as proposed in (1), but users will have the option of upgrading and refactoring one release at a time, which is overall easier.

Ideally, we would have an auto-migration codemod to help with refactoring, but we cannot commit to such tooling at this time. Up until now, I have been eager to proceed with (1) because it would get us to v1.0.0 faster. However, I see the advantages of (2): despite having the excuse of being in a 0.x version to release many breaking changes, it's better for maintainers and users to contend with one breaking change at a time. With that understanding, we'll keep the changes we have so far and will proceed with the cadence outlined in (2). v11 styles themselves come with many breaking changes, and adding onto that may be problematic.

The contribution guide above has been updated accordingly.

cc @metonym @gregorw @SimpleProgrammingAU