[docs] Update the Material UI readme post-v6

[samuelsycamore]

• make Material UI the primary focus of the repo
• add v5 -> v6 upgrade link
• "migration" -> "upgrading"
• add disclaimer that Joy UI is on hold and Material UI is recommended for new projects

Before: https://github.com/mui/material-ui/blob/eea5079a00bedb68e27f22b7f94d9a71cc97ee1e/README.md
After: https://github.com/samuelsycamore/material-ui/blob/readme-update-late-24/README.md

[aarongarciah]

Awesome!

[mui-bot]

Netlify deploy preview

• docs/data/joy/getting-started/overview/overview.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against deefa74

[samuelsycamore]

Reviewing the earlier draft that I submitted, I felt that the Joy UI section was taking up too much space relative to the Material UI section, which should be the main focus. So I reviewed some benchmarks of other popular open source lib readmes and wrote a little more copy about Material UI. Also added a link to MUI X for good measure, because we should be more proactive about directing Material UI users to X. Eventually I think we should link to Toolpad, Pigment CSS, and Base UI as well, but maybe not yet.

[samuelsycamore]

Also updated the Joy UI Getting Started doc to align with the new readme copy:

[oliviertassinari]

I wonder if it wouldn't make sense to extend this a bit more. I could see use explaining Material UI as a library but also a stack, like shadcn.

In v6, this stack is only MUI System + the components.

In v7, this stack could look like this (can be different, only to illustrate our product trends for the last couple of months):

• Base UI (@base-ui/react)
• Material UI System (@material-ui/system), which is a slim wrapper on Pigment CSS, where Pigment CSS supports a runtime with emotion too.
• Pre-designed components following Material Design built on top of those (@material-ui/md3), this package can be in anyone's codebase.

[samuelsycamore]

Something like this? (Should we mention Pigment CSS and/or Base UI as part of the "stack" currently?)

Material UI's core functionality is extended by MUI X, a suite of complex components for advanced use cases.

MUI System is a set of CSS utilities to help you build custom designs more efficiently. For modern CSS-in-JS with static CSS extraction and React Server Component / Next.js App Router support, try Pigment CSS (currently in beta).

[samuelsycamore]

Let's revisit this topic at another time, once this idea is a little more fleshed out. We can continue to iteratively update the readme content beyond the scope of this PR.