[RFC] Deprecate `carbon-components` and `carbon-components-react` #12179

tay1orjones · 2022-09-27T19:08:33Z

tay1orjones
Sep 27, 2022
Maintainer

This is a Request For Comments regarding the intent to deprecate the carbon-components and carbon-components-react packages.

An umbrella issue has been opened for this work:

Deprecate carbon-components and carbon-components-react #12494

Why these packages are being deprecated

In v11 @carbon/styles and @carbon/react were introduced. These are the primary packages intended to be used moving forward. They replace the need for carbon-components and carbon-components-react.

In addition, since releasing v11 we have noticed that having these packages around creates confusion. Project teams are unsure of the relationships between packages, when to use one over the other, and why. Deprecating carbon-components and carbon-components-react should elimitate some of this confusion as the deprecation mechanisms and messaging will point users towards moving to use @carbon/styles and @carbon/react instead.

Proposed timeline

As originally stated in the v11 changelog, we intend to deprecate carbon-components and carbon-components-react in v11, then remove as part of v12¹

Status	Date	Action item
✅	March 2022	v11 is released providing `@carbon/styles` and `@carbon/react`. To facilitate transition, `carbon-components` and `carbon-components-react` are bumped to a new major version and reconfigured to re-export everything from `@carbon/styles` and `@carbon/react`, respectively.
✅	September 2022	Announce intent to deprecate `carbon-components`, `carbon-components-react`, request for comments (this issue).
✅	~~December 2022~~ ~~January 2023~~ March 2023	"Soft deprecation" #12495 - A postinstall message is added to `carbon-components` and `carbon-components` react in the terminal stating our recommendation to move to `@carbon/styles` and `@carbon/react`. The message will link back to this issue for information on the package strategy, deprecation, and plan of action.
✅	May 2023	Recommunicate this plan for deprecation in a long-form article. Published here
-	v12¹	Formal deprecation #12496 - On npm the `carbon-components` and `carbon-components-react` packages are marked as deprecated. `carbon-components` and `carbon-components-react` are removed from the `main` branch and will no longer receive any updates

Current package strategy explained

The packages published are linked in the following ways:

graph LR
    subgraph "Deprecated, to be removed in v12"
    CarbonComponentsReact("carbon-components-react")
    CarbonComponents("carbon-components")
    end

    CarbonReact("@carbon/react")
    CarbonStyles("@carbon/styles")
    OnlyStyles(("Only includes </br>styles/sass modules </br>from these packages, </br>no js exports"))

    CarbonIcons("@carbon/icons")
    CarbonIconsReact("@carbon/icons-react")

    CarbonElements("@carbon/elements")

    subgraph "&quot;Elements&quot; packages"
    CarbonColors("@carbon/colors")
    CarbonGrid("@carbon/grid")
    CarbonLayout("@carbon/layout")
    CarbonMotion("@carbon/motion")
    CarbonThemes("@carbon/themes")
    CarbonType("@carbon/type")
    end

    CarbonReact --> CarbonComponentsReact

    CarbonStyles --> CarbonReact
    CarbonStyles --> CarbonComponents

    CarbonColors --> OnlyStyles
    CarbonGrid   --> OnlyStyles
    CarbonLayout --> OnlyStyles
    CarbonMotion --> OnlyStyles
    CarbonThemes --> OnlyStyles
    CarbonType   --> OnlyStyles
    OnlyStyles   --> CarbonStyles

    CarbonColors --> CarbonElements
    CarbonGrid   --> CarbonElements
    CarbonLayout --> CarbonElements
    CarbonMotion --> CarbonElements
    CarbonThemes --> CarbonElements
    CarbonType   --> CarbonElements

    CarbonIconsReact --> CarbonReact
    CarbonIcons --> CarbonIconsReact

`@carbon/react@1.x`

The @carbon/react package is the flagship offering that houses everything you need to get started building a react app with the Carbon Design System. It includes:

React components
Sass stylesheets/modules
Icons

For most use cases, when using @carbon/react, you should not need the following packages:

@carbon/styles
carbon-components
carbon-components-react
@carbon/icons
@carbon/icons-react
@carbon/colors
@carbon/grid
@carbon/layout
@carbon/motion
@carbon/themes
@carbon/type

It's recommended to start with @carbon/react and to not install other Carbon packages until you find it necessary. If a project was previously using those packages, it may be able to replace usages to instead use @carbon/react and then remove these packages.

Everything from @carbon/styles is included, therefore all styles from the elements packages is included.

`@carbon/styles@1.x`

The @carbon/styles package is dedicated to providing the styles associated with the Carbon Design System. The styles are authored in sass and use the sass module system. It is the successor to carbon-components and recommended to be used instead of carbon-components when you are only in need of styles.

It includes most everything one would need from the elements packages, including the styles, tokens, mixins, etc. from:

@carbon/colors
@carbon/grid
@carbon/layout
@carbon/motion
@carbon/themes
@carbon/type

When using @carbon/styles, it should not be necessary to install any of the above elements packages unless you need to use the javascript exports from those packages.

`carbon-components@v11.x`

We recommend using @carbon/styles instead. This package re-exports everything from @carbon/styles.

`carbon-components-react@v8.x`

We recommend using @carbon/react instead. This package re-exports everything from @carbon/react.

`@carbon/elements`

This package re-exports everything from all the elements packages packages. We recommend installing the individual packages that make up elements as you need them, rather than installing this package.

Elements packages

These packages make up the different elemental building blocks of the system and are organized into logical categories. Each includes styles as well as javascript exports. When using @carbon/react or @carbon/styles, we recommend not installing these packages until you deem it necessary.

There is currently no formal plan or release schedule for v12. This is simply a statement of intent. ↩ ↩²

KTKate · 2022-11-01T18:02:59Z

KTKate
Nov 1, 2022

As someone who's worked through migrating to v11, I think this plan looks great. However, if it's going to result in an influx of devs trying to upgrade to v11 in December, I think the v11 docs could be firmed up a bit more especially with the change in Sass confusing people on top of the changes in Carbon.

The migration guide on the website and the markdown migration guides in Github can be confusing and inconsistent for some things. For example, sometimes it suggests I use @use '@carbon/styles/scss/colors' as *;, while other times, @use '@carbon/react/scss/colors' as *; with no clear way to tell when I should use each. And it never tells me the as * part despite that seeming to be necessary. And if I go to the docs for @carbon/colors, they are still referencing v10. And lastly, perhaps the Storybook can make it really obvious which Carbon version is being shown. At the top it just says something like "@carbon/react@1.16.0" but until you're really familiar with the differences between the v10 and v11, it's hard to tell.

Just my 2 cents after a month or two of working through the migration and having people reach out to me with questions about it.

2 replies

tay1orjones Nov 3, 2022
Maintainer Author

@KTKate This is very helpful feedback, thank you! I agree on all points. I'll try to respond and follow up on each piece you mention:

if it's going to result in an influx of devs trying to upgrade to v11 in December

This is a good point - we could see a big influx of devs trying to upgrade once the message begins showing up in the terminal. It might make sense to shoot for Jan 1 instead.

sometimes it suggests I use @use '@carbon/styles/scss/colors' as *;, while other times, @use '@carbon/react/scss/colors' as *; with no clear way to tell when I should use each

We've been trying to come up with a way to avoid this confusion. We're seeing that most folks miss the message that @carbon/react re-exports everything from @carbon/styles. @carbon/styles isn't needed unless you're building with something other than react. So far we've added some messaging to most places in the docs, migration guide, etc. that basically says "you probably don't need this package"

We've considered updating all docs to use @carbon/react by default instead of mixing the two. Do you think this would eliminate some of the confusion you found? Was it primarily the v11.md migration guide that created this confusion for you and others who reached out to you, or the docs on the website?

And it never tells me the as * part despite that seeming to be necessary

Would it be helpful if we linked out in more places the documentation on Sass module namespaces? Where would this have been most helpful in your journey?

if I go to the docs for @carbon/colors, they are still referencing v10

I can open an issue for this one. Could you link specifically where? The readme and sass docs appear up to date.

perhaps the Storybook can make it really obvious which Carbon version is being shown

We recently added some links to the welcome story to help folks navigate to v10 docs and website, but I agree it could be more clear. I'm not sure how though - if you have any further ideas, let us know.

Again, really appreciate your feedback on this!

KTKate Nov 4, 2022

Thanks for the great reply. I just want to be clear I wasn't trying to nitpick or anything! I just wanted to give some kind of feedback.

IMO for the @carbon/react vs @carbon/styles, I think there should just be a happy path. I believe Carbon is using React as the default implementation so it makes sense to me that the docs would reflect the default paths. I started out on the Migration website where it starts out with the React version and then as you keep scrolling down, transitions into the non-react version. I thought it was just 1 big flow with a couple duplicate parts and ended up @use's with both paths all mixed together. I think just having the React path as the default and then have a "if you use something else, see the migration guide here" type situation would be more streamlined.

In the markdown migration guide, the @carbon/react pathing is mentioned but it wasn't clear to me when I was starting out that I could use the react paths 100% of the time. For example in this screenshot, it mentions the react path in the table but I just thought since the example and the list of API Changes uses the @carbon/styles path, that must be the 'default' one.

The old colors docs are here but basically if you navigate around, especially around the packages level of the folders, a few of the readmes are old. The grid package one uses bx prefixing for example. Now that I've worked through it, I can spot them but in the beginning I was confused all the time.

Would it be helpful if we linked out in more places the documentation on Sass module namespaces? Where would this have been most helpful in your journey?

Yes! So much so! I had not encountered the new Sass before this so I was completely confused. Now that I reflect on it, that colors example in the screen shot above makes it clear that you need to add the colors. before the color variable but I was cmd + fing my way through lists of token/variable name changes thinking I could just find & replace the imports and the variable names.

Thanks for all your work. I cannot even imagine having to juggle the architecture, coding, and documentation all together. So many balls to keep in the air.

tay1orjones · 2023-03-16T20:16:59Z

tay1orjones
Mar 16, 2023
Maintainer Author

For the Formal deprecation, #12496, I think it could make sense to hold off on this until we see usage numbers drop. One possible way would be to use npm downloads as a metric. Once we see usage has dropped significantly we could formally deprecate them.

1 reply

tay1orjones Mar 24, 2023
Maintainer Author

~~Further, we can't formally deprecate the packages on npm until v10 reaches end of life~~

We can still publish updates to deprecated packages, so we could technically deprecate at any point

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Deprecate `carbon-components` and `carbon-components-react` #12179

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 2 comments 3 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

[RFC] Deprecate carbon-components and carbon-components-react #12179

tay1orjones Sep 27, 2022 Maintainer

Why these packages are being deprecated

Proposed timeline

Current package strategy explained

@carbon/react@1.x

@carbon/styles@1.x

carbon-components@v11.x

carbon-components-react@v8.x

@carbon/elements

Elements packages

Footnotes

Replies: 2 comments · 3 replies

KTKate Nov 1, 2022

tay1orjones Nov 3, 2022 Maintainer Author

KTKate Nov 4, 2022

tay1orjones Mar 16, 2023 Maintainer Author

tay1orjones Mar 24, 2023 Maintainer Author

[RFC] Deprecate `carbon-components` and `carbon-components-react` #12179

tay1orjones
Sep 27, 2022
Maintainer

`@carbon/react@1.x`

`@carbon/styles@1.x`

`carbon-components@v11.x`

`carbon-components-react@v8.x`

`@carbon/elements`

Replies: 2 comments 3 replies

KTKate
Nov 1, 2022

tay1orjones Nov 3, 2022
Maintainer Author

tay1orjones
Mar 16, 2023
Maintainer Author

tay1orjones Mar 24, 2023
Maintainer Author