[docs][system] Clean up @mui/styles docs and discourage users from installing it
#39644
Conversation
samuelsycamore
added
docs
Netlify deploy previewBundle size report |
samuelsycamore
changed the title
@mui/styles docs and discourage users from installing it@mui/styles docs and discourage users from installing it
| > It depends on [JSS](https://cssinjs.org/) as a styling solution, which is not used in the `@mui/material` anymore, deprecated in v5. | ||
| > If you don't want to have both Emotion & JSS in your bundle, please refer to the [`@mui/system`](/system/getting-started/) documentation which is the recommended alternative. | ||
| :::error | ||
| `@mui/styles` was deprecated with the release of MUI Core v5 in late 2021. |
There was a problem hiding this comment.
(Note: I was drafting this comment before it was merged 😅 Either way, I'll submit it to foster the discussion)
The only nit-pick thing — though relevant — I'd point out is the "MUI Core" usage. Given this page is sitting on the System docs, I know we're using Core here in the broad sense, but I wonder if it'd be clearer/more accurate to say "Material UI" in this case.
The following sentence makes it slightly more tangled (as in our interchangeable use of Core/Material): "It depended on JSS..." with "it" referring "Core", right? Then, in "which is no longer used in @mui/material" we're being explicit about Material here. It sounds like we want to say "Material UI no longer uses JSS so we deprecated this library".
Anyway, in the efforts to continue tightening up the branding stuff, this is something we may want to discuss further and resolve to avoid any more confusion in the future!
There was a problem hiding this comment.
Yeah I was torn about the usage here, but I figured "Core" was more accurate because it encompasses the suite of related packages being discussed here. Still, I can see both sides. As for "it", that was meant to refer to @mui/styles, so if that's unclear, it might be worthwhile to replace "it" with the actual noun it refers to.
There was a problem hiding this comment.
As an aside, I also considered mentioning @mui/material/styles here, because I've seen confusion between it and @mui/styles - they technically do the same thing (apply styles to your components), and the names are almost identical, but the way they work under the hood is different, so you can't simply swap one for the other 1:1. But then I didn't want to add an additional clarification point that could just confuse some people, so I dunno. 🤷♂️
Related to #39643
We don't maintain
@mui/stylesanymore so we shouldn't invest much effort into these legacy docs, but I noticed some weird styles being applied to the blockquotes on these pages and figured they should be replaced with a much scarier:::errorcallout to discourage users from installing it. I routinely see newer developers on Stack Overflow getting stuck when trying to use@mui/styleswith the latest version of Material UI—presumably because they're following some outdated third-party content—so maybe this will help minimize those issues.I also cut all the intro text in the "Basics" page that referred to it as "Material UI's styling solution" and listed all of the reasons why it's such a great choice. 😅
Before:
After: