ThemeProvider divergence between @theme-ui/core and theme-ui

[ackwell]

Describe the bug Implementation of ThemeProvider is inconsistent depending on what package you pull it from. theme-ui looks to be re-exporting it from @theme-ui/theme-provider, while @theme-ui/core ships its own (simpler) implementation.

While @theme-ui/theme-provider is in-line with the documentation (BodyStyles, et al), blames suggest both have been updated in relatively recent past - so not sure which is the canonical implementation.

To Reproduce Steps to reproduce the behavior:

1. Check sources
2. Notice diverging implementations

(or alternatively, try to use the ThemeProvider from @theme-ui/core and notice it doesn't touch the body styles).

Expected behavior Both packages implement the same behaviour

Screenshots N/A

Additional context N/A

[atanasster]

@ackwell good catch - is seems @theme-ui/theme-provider is just slightly newer (4 months) vs @theme-ui/core (5 months)

imho, we should keep @theme-ui/theme-provider, but since in both cases @hasparus has been involved maybe he has more information.

[dcastil]

The ThemeProvider from @theme-ui/core exists so you can use Theme UI without applying any body styles. I rely on this ThemeProvider myself not to apply any body styles.

This definitely isn't a bug, but the feature isn't documented.

[hasparus]

This is intended, but the naming is kinda misleading here here.

There are four providers here if we wanted to name them in a more self-explanatory manner.

1. ThemeUIThemeProvider in core
2. ThemeUIColorModeProvider
3. ThemeUIMDXProvider
4. ThemeUIThemeColorModeAndMdxProviderWhichAlsoAppliesGlobalBodyStyles

If you take a look at the implementation, @theme-ui/provider imports @theme-ui/core, @theme-ui/color-modes, and '@theme-ui/mdx`.

What do you guys think about renaming the provider from core to ThemeUIThemeProvider? The name clash might cause problems because people use auto-import a lot (I know I do, and I don't pay much attention to the package name tbh).

[hasparus]

How could we help with this problem? @ackwell, do you feel like @theme-ui/core should be documented more thoroughly? How did you encounter the problem?

[ackwell]

Both of the above solutions sound sane (documenting and/or renaming). I chanced on this when testing out a few alternatives within the css-in-js space for a hobby project.

The core misunderstanding came from the documentation - docs on the core package state it can be used stand-alone, and only pull in other packages as required. The same document states it includes a ThemeProvider in the API - that list isn't linked to anything.

The only place that I noticed any documentation on a ThemeProvider was the api documentation page, which (i now know) covers the re-export of @theme-ui/theme-provider, not the more basic one contained in core. As such, I assumed that was the "canonical" API for the component, and was surprised when the one in core diverged.

---

If I was to boil down my confusion to key points,

• @theme-ui/core documentation does not specify the API of the less-featurefull provider
• theme-ui documentation specifies the API of the provider from @theme-ui/theme-provider, but doesn't specify that's where it's from.
• There's no mention of @theme-ui/theme-provider under the navigation "Packages" list, so I assumed it was an internal package that shouldn't be directly consumed.

---

That was a bit longer than intended, whoops! Hopefully it explains my initial confusion.

[atanasster]

I would vote in favor of renaming, and the documentation enhancements.

@ackwell - do you feel like submitting a PR, I will be glad to help or review.

[hasparus]

Thanks for the explanation, ackwell! Yup, I can see how it's confusing now. Okay, I think we can do a few things

• [ ] Rename ThemeProvider in cover to ThemeUICoreProvider.
• [ ] Describe it in the docs. State the difference between the provider here and the provider in theme-ui.
• [ ] Write docs for @theme-ui/theme-provider? It can be used in a MDX+ThemeContext+ColorModes bundle without @theme-ui/components (included in theme-ui), so it could be documented.

[lachlanjc]

At this point, including since MDX is no longer in the ThemeProvider picture, I think a clearer solution would be to update the https://theme-ui.com/packages/core page explaining why you'd want to use core & how it's different. For most users, using theme-ui, the fact that there's multiple options here isn't relevant/are just internal details.