[docs][joy-ui] Revise the Overview page

[danilo-leal]

• I have followed (at least) the PR section of the contributing guide.

This PR revises the Joy UI Overview page, creating sections that we can directly link to in the upcoming marketing page values section. One of the things I attempted to do here is to have a concrete example of all of these values so they're not just abstract things we sell.

Although the previous principles were nice, I don't think they necessarily conveyed everything. Additionally, there was also the opportunity to put it in a more "why" fashion than before. Also, made sure to mention Material UI and Base UI where relevant. Lastly, in the future, this might be a good place to talk more about the design direction ⎯ for now, I just mentioned "Joy Design", so it's officially placed in a doc space and not just in stray GitHub/Notion discussions.

https://deploy-preview-38842--material-ui.netlify.app/joy-ui/getting-started/

[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 32eaa39

[zanivan]

Nice one! It's way easier to scan the page and see the main why's. 🙌

---

I have some thoughts, though:

• The background from the image seems a bit off when on the dark mode. Maybe it'd be better with it coded, or the gradients from Base UI introduction demos bg

---

• I wonder if we could highlight even more the main point of each one of the why's, it might help with the scannability, like for instance on Why use Joy UI:

- Maintained by MUI, Joy UI is an alternative to Material UI for projects that aren't planning to adhere to or use it as a base, the Material Design specifications.
+ Maintained by MUI, **Joy UI is an alternative to Material UI** for projects that **aren't planning to adhere to or use the Material Design** guidelines and visual as a base, .

The idea is to come up with a very targeted first sentence after the title, where we can highlight the main points.

---

All in all, it looks great, and I feel the principles and the other removed items will be more suited to the upcoming design direction doc 🤙

[danilo-leal]

The background from the image seems a bit off when on the dark mode. Maybe it'd be better with it coded, or the gradients from Base UI introduction demos bg

Yeah, I know 😕 This image is being added on the Markdown as an image, not as a component wrapped by the Demo component. I'm not sure we have a way to toggle different images depending on the mode (the blog also doesn't have this feature) but I'd love to!

[zanivan]

I'm not sure we have a way to toggle different images depending on the mode

Maybe we could try doing the same way we do on the templates page with the templates' covers

[danilo-leal]

That could be a way out! I'll wait for @siriwatknp's perspective on this because the template thumbnails have some intricate logic there, a bit more complex than just toggling the file depending on the mode (it's a real screenshot of the current template version).

[danilo-leal]

@samuelsycamore + @siriwatknp let me know if y'all managed to see this!

[samuelsycamore]

Here are some copyediting suggestions! I kind of feel like we're missing some kind of final call to action at the end. Maybe just a line or two to invite the user to move on to installation, or direct them to the Templates from here? I think if I were still debating whether or not to use Joy UI after reading this page, I'd want to jump into some CodeSandboxes and see how these components work before I commit to actually building something myself from scratch to test it out.

[danilo-leal]

@samuelsycamore that makes sense to me, too! It was feeling too abrupt of an ending. Just added a card section, tentatively called "Start now". It's something we could do more on the docs, so it's not just walls of text. We can tweak everything more (content, links, icons, design, etc.) but just wanted to give it a start so we can picture what it could be. Let me know suggestions of stuff we can add and copy for it!

[samuelsycamore]

Love the cards! I added a couple tiny copy edits but will go ahead and tentatively approve 👍