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

```mermaid graph LR CarbonReact("@carbon/react") CarbonStyles("@carbon/styles") OnlyStyles(("Only includes
styles/sass modules
from these packages,
no js exports")) CarbonIcons("@carbon/icons") CarbonIconsReact("@carbon/icons-react") CarbonElements("@carbon/elements") subgraph ""Elements" 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 ``` 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.

- [ ] Move all theme-based documentation from the [color section](https://carbondesignsystem.com/elements/color/overview/) to the [themes section](https://carbondesignsystem.com/elements/themes/overview/). This will intentionally leave the color section much more sparse. Link where necessary to the new themes pages.
- [ ] 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.
- [ ] 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.
- [ ] ...what else?

[github-actions[bot]]

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