Elements packages docs are confusing

[tay1orjones]

The landscape of our elements packages leads to a lot of confusion.

Click to expand a chart of the current landscape

graph LR
   

    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

    

    CarbonStyles --> CarbonReact

    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

Loading

This does not include the additional complexity of what types of assets are provided through each package. Elements packages for instance sometimes contain js and/or sass exports. What exactly they export is not well documented.

Points of confusion

• When would a dev need to install @carbon/elements?
• When would a dev need to install @carbon/colors or @carbon/grid or ... etc. for all elements packages
• What's included in an elements package? Styles? JS Exports?
• Why are tokens listed on the color tokens documentation page different than what's actually exported from @carbon/colors? When/why do I use @carbon/themes with/instead of @carbon/colors
• What parts of the elements packages are available through @carbon/styles?
  • When/why would I install @carbon/colors (or any other elements package) alongside @carbon/styles?
• How does @carbon/react play into all of this?
  • When/why would I install @carbon/colors (or any other elements package) alongside @carbon/react?
• ... what else?

Proposal

To try and improve this situation I think we could explore the following ideas to be more clear in the documentation.

Tasks

Preview Give feedback

1. Move all theme-based documentation from the color section to the themes section. This will intentionally leave the color section much more sparse. Link where necessary to the new themes pages.
2. Update the "code" tab for each elements package to show use through @carbon/react by default, followed by usage with @carbon/styles, with a lower section on when/how/why to install and use the package directly. More clearly and prominently convey the low likelihood of needing to directly and install/use any elements package. Briefly list known use cases for installing/using the packages directly.
3. Update the readme.md for each elements package to generally mirror the updated documentation on the "code" tabs. Default to @carbon/react usage, followed by @carbon/styles, followed by direct install/use of the package.
4. ...what else?

[github-actions]

Thank you for submitting a feature request. Your proposal is open and will soon be triaged by the Carbon team.

If your proposal is accepted and the Carbon team has bandwidth they will take on the issue, or else request you or other volunteers from the community to work on this issue.

[tay1orjones]

One additional suggestion:

Just have docs explain every way you can import smtn like myColor can either be imported by import @carbon/react, import @carbon/color||style , or use @carbon/color||style/scss/myColor