Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Avatar docs page and block examples (#1688)

rubyycheungfa2e26c8c8e3
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs
new file mode 100644
index 0000000000..0b6a9859e6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Avatar — Group',
+ description: 'Overlap multiple avatars in a row to represent a group of people. Use for team lists, PR reviewers, or participant counts where you want to show faces without taking up much space.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx
new file mode 100644
index 0000000000..f165de0194
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import * as stylex from '@stylexjs/stylex';
+
+const USERS = [
+ {
+ name: 'Alice Chen',
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/125033562_1327282494287626_2042282178258670185_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vzgGdeIjaAsQ7kNvwFHfGzn&_nc_oc=AdpvH47kr5fnEWv9bZm7Cgz4YGzVh-jP4pivdmuJu-Ym8LrqtoxumbG4EBHaKE3sP5Yc3G7mzmC2FJZNCNzcmtvt&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=GLOQe78SvUVPef1glEtmsQ&_nc_ss=7a3a8&oh=00_Af3P1YVawrU1yM6TH5D3g9KoFJafkwfn6Jyb6U_sBYC0Xg&oe=69ECC34D',
+ },
+ {
+ name: 'Bob Smith',
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/125177712_365375627873213_5953439887886251969_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=3NVjmTHfk2IQ7kNvwHFZAVJ&_nc_oc=Adpms1qplfKnvE8bmzhU24MgxsNEbNJ8gnjrbDrB3t8VuDcqAEmdQoiSzrBgSCG6lWGvt5NOItuJ4UIYPVbG7vEa&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=-Y0meVgm9bx3SdBmFuHZRg&_nc_ss=7a3a8&oh=00_Af0L5E0SYlatciEXHAcrTaWKDR1JKP8TBD7HZs6wvOSEjg&oe=69ECBF29',
+ },
+ {
+ name: 'Carol Davis',
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/245682593_1255004628297724_3577570150049820589_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=5whLKM1RM6cQ7kNvwEaVbq9&_nc_oc=AdrhyQWW2ege8gqf30rO5lcQYZkZm5px0FUpZ5Xy9Ku8ytqQ7BRu8E3PE2mfeL3XoZLgHziwkpyAVSx5JuIngcAb&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=jnfsnwuykaxT-95F9LitEA&_nc_ss=7a3a8&oh=00_Af31tshg5zaXtReOyztoPwk8MYjKnG0mqIBiUyyaXu8FEQ&oe=69ECAF30',
+ },
+ {
+ name: 'Dan Wilson',
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/125254126_809656226491943_540743226571944946_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vCg2YyCmg8wQ7kNvwHmiD4H&_nc_oc=AdqFfGEd6zdwAc8hDMapKPHvU8umJD4w0HKiVvDJhLk_3Xww__VCIGln0XZ6-46pThhfqNUu6tS-Jx1uzFLVN6vR&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=H25yQ08lrLVo_1RpPU6wwg&_nc_ss=7a3a8&oh=00_Af2vT0tGj7AfYSXac45kd2dwzEWfjzLwpAV_y6hO3Ec-wA&oe=69ECB6C9',
+ },
+ {
+ name: 'Eve Park',
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/124863061_1481250052072229_2189314572828588300_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=9Ryu-r4FG_gQ7kNvwGKdqFO&_nc_oc=Adr5Y_Ui6i4f4I-1_sG55i6AmAU-jwOjlnjrGUkWv0vRIBzXZdtW9Q4xp_99uJ9n6ZeqHPXg7bVeLJNJMIM9K6eB&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=PvhmyvyN5oFeUiI9hncHkA&_nc_ss=7a3a8&oh=00_Af0lT-Bd7ddKAOnib2SY0qwze40acOqzoVWBLrIUHzZzKA&oe=69ECCA1F',
+ },
+];
+
+const groupStyles = stylex.create({
+ overlap: (offset: number) => ({
+ marginLeft: offset,
+ borderRadius: '50%',
+ border: '2px solid var(--color-background-surface, #fff)',
+ }),
+});
+
+export default function AvatarGroup() {
+ return (
+ <XDSStack direction="vertical" gap={8}>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Team members
+ </XDSText>
+ <XDSStack direction="horizontal" vAlign="center">
+ {USERS.map((user, i) => (
+ <XDSStack
+ direction="vertical"
+ key={user.name}
+ {...stylex.props(groupStyles.overlap(i === 0 ? 0 : -10))}>
+ <XDSAvatar src={user.src} name={user.name} size="small" />
+ </XDSStack>
+ ))}
+ <XDSStack
+ direction="vertical"
+ {...stylex.props(groupStyles.overlap(-10))}>
+ <XDSAvatar name="+3" size="small" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Larger group
+ </XDSText>
+ <XDSStack direction="horizontal" vAlign="center">
+ {USERS.slice(0, 3).map((user, i) => (
+ <XDSStack
+ direction="vertical"
+ key={user.name}
+ {...stylex.props(groupStyles.overlap(i === 0 ? 0 : -14))}>
+ <XDSAvatar src={user.src} name={user.name} size="medium" />
+ </XDSStack>
+ ))}
+ <XDSStack
+ direction="vertical"
+ {...stylex.props(groupStyles.overlap(-14))}>
+ <XDSAvatar name="+8" size="medium" />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.doc.mjs
index cc53ef0683..130375be5f 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.doc.mjs
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Avatar — Initials Fallback',
- description: 'Avatars rendering initials from user names when no image is available.',
+ name: 'Avatar — Initials',
+ description: 'Show initials instead of a photo. The avatar extracts the first and last initials from the name automatically. Use when you only have a user name, like in anonymous accounts or new user onboarding.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Avatar'],
+ aspectRatio: 1,
+ componentsUsed: ['Avatar', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx
index c0b3a3ccd6..be253d1409 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarInitialsFallback.tsx
@@ -1,14 +1,27 @@
'use client';
import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const NAMES = [
+ {name: 'John Doe', note: 'First + last'},
+ {name: 'Alice', note: 'Single name'},
+ {name: 'Bob Smith Johnson', note: 'Multi-word'},
+ {name: 'Dr. Sarah Connor', note: 'Prefixed'},
+];
export default function AvatarInitialsFallback() {
return (
- <div style={{display: 'flex', alignItems: 'center', gap: 16}}>
- <XDSAvatar name="John Doe" size="medium" />
- <XDSAvatar name="Alice" size="medium" />
- <XDSAvatar name="Bob Smith Johnson" size="medium" />
- <XDSAvatar name="Dr. Sarah Connor" size="medium" />
- </div>
+ <XDSStack direction="horizontal" gap={6} vAlign="center">
+ {NAMES.map(({name, note}) => (
+ <XDSStack key={name} direction="vertical" gap={2} hAlign="center">
+ <XDSAvatar name={name} size="medium" />
+ <XDSText type="supporting" color="secondary">
+ {note}
+ </XDSText>
+ </XDSStack>
+ ))}
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.doc.mjs
new file mode 100644
index 0000000000..331506e2fe
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Avatar — User Card',
+ description: 'Place an avatar next to a name and role to create a user card row. Use for comment headers, contact lists, profile sections, or anywhere you need to identify a person at a glance.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.tsx
new file mode 100644
index 0000000000..3dadfed53e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarUserCard.tsx
@@ -0,0 +1,57 @@
+'use client';
+
+import {XDSAvatar, XDSAvatarStatusDot} from '@xds/core/Avatar';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const USERS = [
+ {
+ name: 'Alice Chen',
+ role: 'Engineering Lead',
+ variant: 'positive' as const,
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/125033562_1327282494287626_2042282178258670185_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vzgGdeIjaAsQ7kNvwFHfGzn&_nc_oc=AdpvH47kr5fnEWv9bZm7Cgz4YGzVh-jP4pivdmuJu-Ym8LrqtoxumbG4EBHaKE3sP5Yc3G7mzmC2FJZNCNzcmtvt&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=GLOQe78SvUVPef1glEtmsQ&_nc_ss=7a3a8&oh=00_Af3P1YVawrU1yM6TH5D3g9KoFJafkwfn6Jyb6U_sBYC0Xg&oe=69ECC34D',
+ },
+ {
+ name: 'Bob Smith',
+ role: 'Product Designer',
+ variant: 'neutral' as const,
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/245682593_1255004628297724_3577570150049820589_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=5whLKM1RM6cQ7kNvwEaVbq9&_nc_oc=AdrhyQWW2ege8gqf30rO5lcQYZkZm5px0FUpZ5Xy9Ku8ytqQ7BRu8E3PE2mfeL3XoZLgHziwkpyAVSx5JuIngcAb&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=jnfsnwuykaxT-95F9LitEA&_nc_ss=7a3a8&oh=00_Af31tshg5zaXtReOyztoPwk8MYjKnG0mqIBiUyyaXu8FEQ&oe=69ECAF30',
+ },
+ {
+ name: 'Carol Davis',
+ role: 'Engineering Manager',
+ variant: 'negative' as const,
+ src: 'https://scontent.xx.fbcdn.net/v/t39.6806-6/125254126_809656226491943_540743226571944946_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vCg2YyCmg8wQ7kNvwHmiD4H&_nc_oc=AdqFfGEd6zdwAc8hDMapKPHvU8umJD4w0HKiVvDJhLk_3Xww__VCIGln0XZ6-46pThhfqNUu6tS-Jx1uzFLVN6vR&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=H25yQ08lrLVo_1RpPU6wwg&_nc_ss=7a3a8&oh=00_Af2vT0tGj7AfYSXac45kd2dwzEWfjzLwpAV_y6hO3Ec-wA&oe=69ECB6C9',
+ },
+];
+
+export default function AvatarUserCard() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ {USERS.map(user => (
+ <XDSStack
+ key={user.name}
+ direction="horizontal"
+ gap={3}
+ vAlign="center">
+ <XDSAvatar
+ src={user.src}
+ name={user.name}
+ size="medium"
+ status={
+ <XDSAvatarStatusDot variant={user.variant} label={user.variant} />
+ }
+ />
+ <XDSStack direction="vertical" gap={0}>
+ <XDSText type="body" weight="bold">
+ {user.name}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {user.role}
+ </XDSText>
+ </XDSStack>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.doc.mjs
index 220cb4de47..8e1aece495 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.doc.mjs
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Avatar — With Images',
- description: 'Avatars with profile images shown at different sizes.',
+ name: 'Avatar — Photo',
+ description: 'Show a profile photo at different sizes. Use when you have a user photo URL. If the image fails to load, initials are shown instead.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Avatar'],
+ aspectRatio: 1,
+ componentsUsed: ['Avatar', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.tsx
index 0fdbb7ef7b..0b58c71b7f 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.tsx
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarWithImage.tsx
@@ -1,30 +1,31 @@
'use client';
import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSStack} from '@xds/core/Layout';
export default function AvatarWithImage() {
return (
- <div style={{display: 'flex', alignItems: 'center', gap: 16}}>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
<XDSAvatar
- src="https://i.pravatar.cc/150?img=1"
- name="User 1"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/125033562_1327282494287626_2042282178258670185_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vzgGdeIjaAsQ7kNvwFHfGzn&_nc_oc=AdpvH47kr5fnEWv9bZm7Cgz4YGzVh-jP4pivdmuJu-Ym8LrqtoxumbG4EBHaKE3sP5Yc3G7mzmC2FJZNCNzcmtvt&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=GLOQe78SvUVPef1glEtmsQ&_nc_ss=7a3a8&oh=00_Af3P1YVawrU1yM6TH5D3g9KoFJafkwfn6Jyb6U_sBYC0Xg&oe=69ECC34D"
+ name="Alice Chen"
size="tiny"
/>
<XDSAvatar
- src="https://i.pravatar.cc/150?img=2"
- name="User 2"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/125177712_365375627873213_5953439887886251969_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=3NVjmTHfk2IQ7kNvwHFZAVJ&_nc_oc=Adpms1qplfKnvE8bmzhU24MgxsNEbNJ8gnjrbDrB3t8VuDcqAEmdQoiSzrBgSCG6lWGvt5NOItuJ4UIYPVbG7vEa&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=-Y0meVgm9bx3SdBmFuHZRg&_nc_ss=7a3a8&oh=00_Af0L5E0SYlatciEXHAcrTaWKDR1JKP8TBD7HZs6wvOSEjg&oe=69ECBF29"
+ name="Bob Smith"
size="small"
/>
<XDSAvatar
- src="https://i.pravatar.cc/150?img=3"
- name="User 3"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/245682593_1255004628297724_3577570150049820589_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=5whLKM1RM6cQ7kNvwEaVbq9&_nc_oc=AdrhyQWW2ege8gqf30rO5lcQYZkZm5px0FUpZ5Xy9Ku8ytqQ7BRu8E3PE2mfeL3XoZLgHziwkpyAVSx5JuIngcAb&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=jnfsnwuykaxT-95F9LitEA&_nc_ss=7a3a8&oh=00_Af31tshg5zaXtReOyztoPwk8MYjKnG0mqIBiUyyaXu8FEQ&oe=69ECAF30"
+ name="Carol Davis"
size="medium"
/>
<XDSAvatar
- src="https://i.pravatar.cc/150?img=4"
- name="User 4"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/125254126_809656226491943_540743226571944946_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vCg2YyCmg8wQ7kNvwHmiD4H&_nc_oc=AdqFfGEd6zdwAc8hDMapKPHvU8umJD4w0HKiVvDJhLk_3Xww__VCIGln0XZ6-46pThhfqNUu6tS-Jx1uzFLVN6vR&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=H25yQ08lrLVo_1RpPU6wwg&_nc_ss=7a3a8&oh=00_Af2vT0tGj7AfYSXac45kd2dwzEWfjzLwpAV_y6hO3Ec-wA&oe=69ECB6C9"
+ name="Dan Wilson"
size="large"
/>
- </div>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.doc.mjs
index 581e13e762..4d650be83b 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.doc.mjs
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Avatar — With Status Indicators',
- description: 'Avatars with positive, neutral, and negative status dots for online presence.',
+ name: 'Avatar — Status Dot',
+ description: 'Add a status dot to an avatar to show whether someone is online, away, or busy. Use in chat, messaging, or any UI where knowing availability matters.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Avatar'],
+ aspectRatio: 1,
+ componentsUsed: ['Avatar', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.tsx
index 5c726e3a07..a9422a6081 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.tsx
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarWithStatus.tsx
@@ -1,28 +1,29 @@
'use client';
import {XDSAvatar, XDSAvatarStatusDot} from '@xds/core/Avatar';
+import {XDSStack} from '@xds/core/Layout';
export default function AvatarWithStatus() {
return (
- <div style={{display: 'flex', alignItems: 'center', gap: 16}}>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
<XDSAvatar
- src="https://i.pravatar.cc/150?img=20"
- name="Online User"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/125033562_1327282494287626_2042282178258670185_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=vzgGdeIjaAsQ7kNvwFHfGzn&_nc_oc=AdpvH47kr5fnEWv9bZm7Cgz4YGzVh-jP4pivdmuJu-Ym8LrqtoxumbG4EBHaKE3sP5Yc3G7mzmC2FJZNCNzcmtvt&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=GLOQe78SvUVPef1glEtmsQ&_nc_ss=7a3a8&oh=00_Af3P1YVawrU1yM6TH5D3g9KoFJafkwfn6Jyb6U_sBYC0Xg&oe=69ECC34D"
+ name="Alice Chen"
size="large"
status={<XDSAvatarStatusDot variant="positive" label="Online" />}
/>
<XDSAvatar
- src="https://i.pravatar.cc/150?img=21"
- name="Offline User"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/245682593_1255004628297724_3577570150049820589_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=5whLKM1RM6cQ7kNvwEaVbq9&_nc_oc=AdrhyQWW2ege8gqf30rO5lcQYZkZm5px0FUpZ5Xy9Ku8ytqQ7BRu8E3PE2mfeL3XoZLgHziwkpyAVSx5JuIngcAb&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=jnfsnwuykaxT-95F9LitEA&_nc_ss=7a3a8&oh=00_Af31tshg5zaXtReOyztoPwk8MYjKnG0mqIBiUyyaXu8FEQ&oe=69ECAF30"
+ name="Bob Smith"
size="large"
status={<XDSAvatarStatusDot variant="neutral" label="Offline" />}
/>
<XDSAvatar
- src="https://i.pravatar.cc/150?img=22"
- name="Busy User"
+ src="https://scontent.xx.fbcdn.net/v/t39.6806-6/124863061_1481250052072229_2189314572828588300_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=56bbc2&_nc_ohc=9Ryu-r4FG_gQ7kNvwGKdqFO&_nc_oc=Adr5Y_Ui6i4f4I-1_sG55i6AmAU-jwOjlnjrGUkWv0vRIBzXZdtW9Q4xp_99uJ9n6ZeqHPXg7bVeLJNJMIM9K6eB&_nc_zt=14&_nc_ht=scontent.xx&_nc_gid=PvhmyvyN5oFeUiI9hncHkA&_nc_ss=7a3a8&oh=00_Af0lT-Bd7ddKAOnib2SY0qwze40acOqzoVWBLrIUHzZzKA&oe=69ECCA1F"
+ name="Carol Davis"
size="large"
status={<XDSAvatarStatusDot variant="negative" label="Busy" />}
/>
- </div>
+ </XDSStack>
);
}
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index 555155e11b..d5dd75f20f 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -6,12 +6,19 @@ export const docs = {
keywords: ["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],
usage: {
description:
- 'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
+ 'Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.',
bestPractices: [
- {guidance: true, description: 'Always provide a name prop so the component can generate meaningful initials and alt text when the image fails to load.'},
- {guidance: true, description: 'Use the status slot with XDSAvatarStatusDot to indicate online presence or availability when relevant to the context.'},
- {guidance: false, description: 'Use Avatar for decorative images or logos that aren\'t representing a person or entity — use an image or icon component instead.'},
- {guidance: false, description: 'Override the circular shape — Avatars are always round to maintain visual consistency across the system.'},
+ {guidance: true, description: 'Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.'},
+ {guidance: true, description: 'Pick a size that matches the context — tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers.'},
+ {guidance: true, description: 'Add a status dot when knowing someone\'s availability matters, like in chat or team views.'},
+ {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team — use an image or icon instead.'},
+ {guidance: false, description: 'Force a square or custom shape — avatars are always circular to stay consistent across the system.'},
+ ],
+ anatomy: [
+ {name: 'Photo', required: false, description: 'The profile image, loaded from the src URL. Shown when available.'},
+ {name: 'Initials', required: false, description: 'One or two letters extracted from the name. Shown when no photo is available.'},
+ {name: 'Default icon', required: false, description: 'A generic person silhouette. Shown when there is no photo or name.'},
+ {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy).'},
],
},
theming: {
@@ -141,15 +148,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'user avatar w/ profile pictures + fallback support',
+ description: 'person/team avatar w/ photo → initials → icon fallback chain',
usage: {
description:
- 'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
+ 'Avatar represents a person or team with a profile photo, initials, or a default icon. Falls back automatically. Use in comment headers, contact lists, chat, user cards.',
bestPractices: [
- {guidance: true, description: 'Always provide a name prop so the component can generate meaningful initials and alt text when the image fails to load.'},
- {guidance: true, description: 'Use the status slot with XDSAvatarStatusDot to indicate online presence or availability when relevant to the context.'},
- {guidance: false, description: 'Use Avatar for decorative images or logos that aren\'t representing a person or entity — use an image or icon component instead.'},
- {guidance: false, description: 'Override the circular shape — Avatars are always round to maintain visual consistency across the system.'},
+ {guidance: true, description: 'Always pass a name for initials fallback and screen reader alt text.'},
+ {guidance: true, description: 'Match size to context — tiny/xsmall inline, small/medium in lists, large for profiles.'},
+ {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
+ {guidance: false, description: 'Use for logos or product images — use an image or icon instead.'},
+ {guidance: false, description: 'Force a square or custom shape — avatars are always circular.'},
],
},
components: [