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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.mjsindex 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: [