[system][docs] Clarifying differences between JSS- and Emotion-based `styled` utilities

[memo-saldana]

Duplicates

• [X] I have searched the existing issues

Related page

https://mui.com/material-ui/migration/v5-style-changes/#styled

Kind of issue

Unclear explanations

Issue description

I was looking for ... and it appears that ... I was looking into how to create reusable styled components. It appears that there are a couple of places from which I can import the utility fn, but it is not clear which is the correct one (or if all are the same?).

Migration guide says to change any usages of

-import { styled } from '@mui/material/styles';
+import { styled } from '@mui/styles';

But...

• documentation for @mui/styles states that this is a legacy api.
• documentation for styled states to use @mui/material/styles
• tangential documentation uses @mui/material/styles

From the amount of ocurrences, seems like migration docs is outdated. Maybe its the same under the hood? Could anyone shed some light here? Thanks!

Context 🔦

I just migrated a project from v4 to v5.

[samuelsycamore]

Thanks for pointing this out @memo-saldana! @mui/styles is indeed a legacy package that's no longer recommended, and the doc you linked is a little confusing.

I think that confusion stems from the fact that both @mui/material/styles AND @mui/styles both provide something called styled—but that something is actually not the same thing in the two packages.

In that section that you linked from the Migration Guide, what it's saying is that the older JSS-based styled utility is no longer exported from @mui/material/styles, and so if you still need it, you must import from it @mui/styles (the deprecated package). By contrast, the styled utility that is now exported by @mui/material/styles uses Emotion under the hood rather than JSS, so the way it works slightly different (hence the breaking changes). Does that make sense?