[docs] Iterating on recent Joy UI Component page updates

[mapache-salvaje]

Part of #33998

Following #34858, #35152, and #34838, as well as some internal discussions with the Core team about these docs, I wanted to do a quick second pass on these three pages (Alert, Aspect Ratio, and Avatar) together to apply some structural changes based on what we've discovered so far.

Changes include:

• removing info about overriding props (unnecessary on component pages, and soon we'll have a guide with [docs] Add guides to overriding component structure in Base UI and Joy UI docs #34990)
• moving Anatomy section to the bottom of the page - I think this is preferable for now, though we've discussed creating a new tab on the page for this info
• rearranging the Customization section - common props like Variants, Sizes, Decorators, Colors, etc. get bumped to the top, and in a consistent order
• adding h3s under Basics when Customization h3s feel more... "basic" 😅 than "customization" (i.e. adding images to Avatars feels like a basic implementation of the component)
• standardizing "Usage with" sections as differentiated from Customization
• standardizing shared/repeated text
• adding a tiny adjustment to one of the Alert demos that never got committed before that PR was merged, which helps to make them look less like buttons

I had intended to include these edits with my revision of the Autocomplete page, but because that doc is so huge, it really needs its own PR. It's shown me some structural things we need to account for as these pages get bigger—namely, that if everything is classified as "Customization," then this header starts to lose meaning. We also need to be intentional about the order in which information is presented under the Customization header, to deliver a more consistent experience across the docs.

[mui-bot]

	Messages
📖	Netlify deploy preview: https://deploy-preview-35162--material-ui.netlify.app/

No bundle size changes

Generated by 🚫 dangerJS against f39869f

[mapache-salvaje]

@oliviertassinari Moving the conversation from #35152—

1. Should we remove the Usage section entirely from these docs? Is it unnecessary/unhelpful?
2. Usage with sections - should we edit these headers to simply name the thing that the component is being used with (Avatar Group, Next.js Image component, etc.)?
3. Related to 2 - should we differentiate between usage with "standalone" components (Avatar with Badge) vs. "supplemental" components (Avatar with Avatar Group)?

cc @danilo-leal and @siriwatknp I would love to get your thoughts on these questions.

[oliviertassinari]

1. I think that ## Usage bring value when it can't be replaced by a basic demo that is simple enough to be expanded by default. For example, it brings clarity to most of MUI Base components. https://mui.com/base/react-switch/#basics is way too noisy to serve the same purpose. However, when the basic demo is simple enough, I think that it is much clearer.
2. 🤷‍♂️
3. 🤷‍♂️

[siriwatknp]

1. I think that the current ## Usage is not helpful or incomplete. What I get to see is how to import it but it does not work when I copy the code to my project (I don't see anything on my screen):

   import Avatar from '@mui/joy/Avatar';
    
    export default function MyApp() {
      return <Avatar />;
    }

   I think it can be removed, at least for Joy UI. I guess developers prefer to look at the demo and open a Sandbox if they want to make changes.

   Maybe changing to ## Import sounds better to me because I can copy the import directly.

2. I think Usage with helps me understand that it involves other components. I feel that it is better than the previous version. Maybe just With ... is enough and using the component name sounds better to me (without the space):

   • ## With AvatarGroup
   • ## With Badge
   • ## With Next.js Image

3. I don't see that much difference at this point.

[mapache-salvaje]

OK, I'm cool with removing the Usage section altogether, and ensuring that the Basics section includes a very basic demo that can serve as a more useful replacement for what the Usage section attempts to communicate. In situations where the Usage section might provide details that aren't covered elsewhere, I'll try moving them to Basics or the Introduction.

[mapache-salvaje]

After reflecting on @siriwatknp's comment above, I agree that the import—specifically, being able to copy and paste it—is the most useful part of the Usage section code snippet. I moved this to the Basics section. I also added imports for the "Usage with" sections that involve other Joy UI components, so those can be easily copied and pasted in as well. I think it also helps to quickly visually clarify that this section involves introducing a new component.

[siriwatknp]

🤩 Love it!

[mapache-salvaje]

Thanks for the clean new Alert demo @oliviertassinari! This PR should be ready to go, and now I think we have a much better template to proceed with.

[siriwatknp]

👍 Well done!