[docs] Revise the Joy UI "Avatar" component page (#35152)

docs/data/joy/components/avatar/FallbackAvatars.js

@@ -6,7 +6,7 @@ export default function FallbackAvatars() {
   return (
     <Box sx={{ display: 'flex', gap: 2 }}>
       <Avatar alt="Remy Sharp" src="/broken-image.jpg">
-        B
+        BT
       </Avatar>
       <Avatar alt="Remy Sharp" src="/broken-image.jpg" />
       <Avatar src="/broken-image.jpg" />

docs/data/joy/components/avatar/FallbackAvatars.tsx

@@ -6,7 +6,7 @@ export default function FallbackAvatars() {
   return (
     <Box sx={{ display: 'flex', gap: 2 }}>
       <Avatar alt="Remy Sharp" src="/broken-image.jpg">
-        B
+        BT
       </Avatar>
       <Avatar alt="Remy Sharp" src="/broken-image.jpg" />
       <Avatar src="/broken-image.jpg" />

docs/data/joy/components/avatar/FallbackAvatars.tsx.preview

@@ -1,5 +1,5 @@
 <Avatar alt="Remy Sharp" src="/broken-image.jpg">
-  B
+  BT
 </Avatar>
 <Avatar alt="Remy Sharp" src="/broken-image.jpg" />
 <Avatar src="/broken-image.jpg" />

docs/data/joy/components/avatar/avatar.md

@@ -6,11 +6,11 @@ githubLabel: 'component: avatar'
 
 # Avatar
 
-<p class="description">Avatar represents a person that contains an image or initials which can also be presented in a group with multiple avatars.</p>
+<p class="description">An avatar is a graphical representation of a user's identity.</p>
 
 ## Introduction
 
-The avatar component is usually seen for displaying user information in places such as menus, tables, and chats.
+The Avatar component can be used to display graphical information about a user in places such as menus, tables, and chats.
 
 {{"demo": "AvatarUsage.js", "hideToolbar": true}}
 
@@ -28,58 +28,76 @@ export default function MyApp() {
 }
 ```
 
-### Sizes
-
-The avatar components comes with three sizes out of the box: `sm`, `md` (the default), and `lg`.
-
-{{"demo": "AvatarSizes.js"}}
+## Basics
 
-:::success
-To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
-:::
+By default, the Avatar component displays a generic Person Icon.
+Wrap it around a string to display plain text, or use the `src` prop to display an image.
 
-### Variants
+## Anatomy
 
-The avatar component supports the four global variants: `soft` (default), `solid`, `outlined`, and `plain`.
+The Avatar component is composed of a root `<div>` that may wrap around an `<svg>`, an `<img>`, or a string:
 
-{{"demo": "AvatarVariants.js"}}
+```html
+<div class="JoyAvatar-root">
+  <!-- Avatar contents -->
+</div>
+```
 
-:::success
-To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
-:::
+## Customization
 
-### Initials
+### Text Avatar
 
-Use a string as children to display its initials on the avatar component.
+Wrap the Avatar component around a string to display text.
+Note that the Avatar is designed to comfortably fit two letters at most—for instance, a user's initials:
 
 {{"demo": "InitialAvatars.js"}}
 
-### Image
+### Image Avatar
 
-Insert images in the avatar by using a path inside the `src` prop, similar to how you'd do in the HTML `<img>` element.
-Make sure to to write a meaningful description in the `alt` prop.
+Insert images into the Avatar by defining a path inside the `src` prop, just like you would with an HTML `<img>` element.
+Make sure to to write a meaningful description for the `alt` prop.
 
 {{"demo": "ImageAvatars.js"}}
 
 ### Image fallbacks
 
-If an error occurs while loading the avatar image, it will fallback to alternatives in the following order:
+If an error occurs while loading the Avatar's image, it will fall back to the following alternatives (in this order):
 
-1. The provided children string.
-2. The first letter of the `alt` text.
-3. A generic icon.
+1. The provided child string
+2. The first letter of the alt text
+3. The default generic icon
 
 {{"demo": "FallbackAvatars.js"}}
 
-### With a badge
+### Variants
+
+The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`.
+
+{{"demo": "AvatarVariants.js"}}
+
+:::success
+To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
+:::
+
+### Sizes
 
-Combine the avatar component with the [`Badge`](/joy-ui/react-badge/) to extend what you can communicate with it.
+The Avatar component comes in three sizes: `sm`, `md` (the default), and `lg`:
+
+{{"demo": "AvatarSizes.js"}}
+
+:::success
+To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
+:::
+
+## Usage with the Badge
+
+Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status:
 
 {{"demo": "BadgeAvatars.js"}}
 
-### Group
+## Usage with the Avatar Group
 
-Use `AvatarGroup` component to group multiple avatars together.
+Use the Avatar Group component to group multiple Avatars together.
 
 ```jsx
 import AvatarGroup from '@mui/joy/AvatarGroup';
@@ -89,44 +107,43 @@ import AvatarGroup from '@mui/joy/AvatarGroup';
 
 ### Quantity within a group
 
-The `AvatarGroup` does not provide built-in props to control the maximum and the total number of avatars within a group.
-This is because customization is broader if you have full control of the logic.
+The Avatar Group does not provide built-in props to control the maximum or the total number of Avatars within a group.
+This is intentionally left open-ended to give you broader options for customization.
 
-Use the snippet below as insipiration to create that:
+The demo below shows an example of an Avatar Group that maxes out at five; all Avatars beyond the first four are lumped together in the fifth Avatar, which displays the total number hidden:
 
 {{"demo": "MaxAndTotalAvatars.js"}}
 
-### Ellipsis action
+### Consistent appearance
 
-`Avatar` exposes meaningful CSS variables to communicate with `AvatarGroup`.
-You can apply those variables to other components to mimic the avatar appearance inside a group.
-This customization technique makes your interface more resilient to changes.
+The Avatar component exposes meaningful CSS variables to communicate with Avatar Group.
+You can apply those variables to other non-Avatar components to mimic the Avatar's appearance inside of a group.
+This customization technique makes your interface more resilient to changes, as any style changes applied to the Avatar will also be applied to the other components in the group.
 
-Here is an example of using `IconButton` component to create an ellipsis action:
+Here is an example using an Icon Button with its styles defined by the Avatar's CSS variables:
 
 {{"demo": "EllipsisAvatarAction.js"}}
 
 ### Overlapping order
 
-By default, the first avatar in the group stays behind the second and so on.
-You can reverse the overlapping order by reversing avatars position and using the CSS `flexDirection: row-reverse` property in the `AvatarGroup`.
+By default, the first Avatar in the group sits behind the second, which sits behind the third, and so on.
+You can reverse the overlapping order by reversing the order of the Avatars and using the CSS `flexDirection: row-reverse` property in the Avatar Group:
 
 {{"demo": "OverlapAvatarGroup.js"}}
 
-### Vertical
+### Vertical stacking
 
-To render the `AvatarGroup` vertically, add the CSS `writing-mode: vertical-rl` property to the it and rotate the extra element, if existent, by -90 degrees.
+To render the Avatar Group vertically, add the CSS `writing-mode: vertical-rl` property and rotate the interior element (if one is present) by -90 degrees.
 
 :::info
-**Tip:** Give preference to this approach as it preserves the overlapping offset between avatars whereas `flexDirection: column` don't.
+This approach is preferable because it preserves the overlapping offset between Avatars; the alternative—`flexDirection: column`—does not.
 :::
 
 {{"demo": "VerticalAvatarGroup.js"}}
 
-## CSS variables
-
-Play around with all the CSS variables available in the slider component to see how the design changes.
+## CSS variable playground
 
-You can use those to customize the component on both the `sx` prop and the theme.
+Play around with the CSS variables available to the Avatar component to see how the design changes.
+You can use these to customize the component with both the `sx` prop and the theme.
 
 {{"demo": "AvatarGroupVariables.js", "hideToolbar": true }}