Skip to content

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

TypeScript

feat(Avatar): add size-aware XDSAvatarStatusDot component (#242)

rubyycheungf37774c533d4
diff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsx
index 659c4733da..4a102ea8ef 100644
--- a/apps/storybook/stories/Avatar.stories.tsx
+++ b/apps/storybook/stories/Avatar.stories.tsx
@@ -1,11 +1,9 @@
import type {Meta, StoryObj} from '@storybook/react';
import * as stylex from '@stylexjs/stylex';
import {XDSAvatar} from '@xds/core/Avatar';
-import {
- colorVars,
- spacingVars,
- typographyVars,
-} from '@xds/core/theme/tokens.stylex';
+import {XDSAvatarStatusDot} from '@xds/core/Avatar';
+import {spacingVars, typographyVars} from '@xds/core/theme/tokens.stylex';
+import {CheckIcon} from '@heroicons/react/24/solid';
const styles = stylex.create({
storyWrapper: {
@@ -22,38 +20,8 @@ const styles = stylex.create({
margin: `0 0 ${spacingVars['--spacing-2']} 0`,
fontFamily: typographyVars['--font-body'],
},
- statusDot: {
- width: 10,
- height: 10,
- borderRadius: '50%',
- backgroundColor: colorVars['--color-positive'],
- borderWidth: 2,
- borderStyle: 'solid',
- borderColor: colorVars['--color-surface'],
- },
- statusDotOffline: {
- backgroundColor: colorVars['--color-text-secondary'],
- },
- statusDotBusy: {
- backgroundColor: colorVars['--color-negative'],
- },
});
-// Simple status indicator component for demos
-const StatusDot = ({
- status = 'online',
-}: {
- status?: 'online' | 'offline' | 'busy';
-}) => (
- <div
- {...stylex.props(
- styles.statusDot,
- status === 'offline' && styles.statusDotOffline,
- status === 'busy' && styles.statusDotBusy,
- )}
- />
-);
-
const meta: Meta<typeof XDSAvatar> = {
title: 'Core/XDSAvatar',
component: XDSAvatar,
@@ -104,7 +72,7 @@ const meta: Meta<typeof XDSAvatar> = {
control: 'boolean',
description: 'Show status indicator dot',
mapping: {
- true: <StatusDot />,
+ true: <XDSAvatarStatusDot />,
false: undefined,
},
},
@@ -262,19 +230,121 @@ export const WithStatus: Story = {
src="https://i.pravatar.cc/150?img=20"
name="Online User"
size="large"
- status={<StatusDot status="online" />}
+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}
/>
<XDSAvatar
src="https://i.pravatar.cc/150?img=21"
name="Offline User"
size="large"
- status={<StatusDot status="offline" />}
+ status={<XDSAvatarStatusDot variant="neutral" label="Offline" />}
/>
<XDSAvatar
src="https://i.pravatar.cc/150?img=22"
name="Busy User"
size="large"
- status={<StatusDot status="busy" />}
+ status={<XDSAvatarStatusDot variant="negative" label="Busy" />}
+ />
+ </div>
+ </div>
+ ),
+};
+
+export const StatusAcrossAllSizes: Story = {
+ name: 'Status Dot Across All Sizes',
+ render: () => (
+ <div {...stylex.props(styles.storyWrapper)}>
+ <h4 {...stylex.props(styles.heading)}>
+ Status dot scales proportionally with avatar size
+ </h4>
+
+ <h4 {...stylex.props(styles.heading)}>Named Sizes</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ name="TY"
+ size="tiny"
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ name="XS"
+ size="xsmall"
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ name="SM"
+ size="small"
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ name="MD"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ name="LG"
+ size="large"
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ </div>
+
+ <h4 {...stylex.props(styles.heading)}>Numeric Sizes with Images</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=30"
+ name="U1"
+ size={20}
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=31"
+ name="U2"
+ size={32}
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=32"
+ name="U3"
+ size={48}
+ status={<XDSAvatarStatusDot variant="negative" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=33"
+ name="U4"
+ size={72}
+ status={<XDSAvatarStatusDot variant="neutral" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=34"
+ name="U5"
+ size={96}
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=35"
+ name="U6"
+ size={128}
+ status={<XDSAvatarStatusDot variant="positive" />}
+ />
+ </div>
+
+ <h4 {...stylex.props(styles.heading)}>All Colors at Medium</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=40"
+ name="Positive"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=41"
+ name="Neutral"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="neutral" label="Offline" />}
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=42"
+ name="Negative"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="negative" label="Busy" />}
/>
</div>
</div>
@@ -286,10 +356,198 @@ export const StatusWithSizes: Story = {
<div {...stylex.props(styles.storyWrapper)}>
<h4 {...stylex.props(styles.heading)}>Status with Different Sizes</h4>
<div {...stylex.props(styles.row)}>
- <XDSAvatar name="AB" size="small" status={<StatusDot />} />
- <XDSAvatar name="CD" size="medium" status={<StatusDot />} />
- <XDSAvatar name="EF" size="large" status={<StatusDot />} />
- <XDSAvatar name="GH" size={72} status={<StatusDot />} />
+ <XDSAvatar name="AB" size="small" status={<XDSAvatarStatusDot />} />
+ <XDSAvatar name="CD" size="medium" status={<XDSAvatarStatusDot />} />
+ <XDSAvatar name="EF" size="large" status={<XDSAvatarStatusDot />} />
+ <XDSAvatar name="GH" size={72} status={<XDSAvatarStatusDot />} />
+ </div>
+ </div>
+ ),
+};
+
+export const StatusWithIcon: Story = {
+ name: 'Status Dot with Icon',
+ render: () => (
+ <div {...stylex.props(styles.storyWrapper)}>
+ <h4 {...stylex.props(styles.heading)}>
+ Icon inside status dot (hidden at tiny sizes where there isn't room)
+ </h4>
+
+ <h4 {...stylex.props(styles.heading)}>Named Sizes</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ name="TY"
+ size="tiny"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ name="XS"
+ size="xsmall"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ name="SM"
+ size="small"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=50"
+ name="MD"
+ size="medium"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=51"
+ name="LG"
+ size="large"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ </div>
+
+ <h4 {...stylex.props(styles.heading)}>Numeric Sizes with Images</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=30"
+ name="U1"
+ size={20}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=31"
+ name="U2"
+ size={32}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=32"
+ name="U3"
+ size={48}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=33"
+ name="U4"
+ size={72}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=34"
+ name="U5"
+ size={96}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=35"
+ name="U6"
+ size={128}
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ </div>
+
+ <h4 {...stylex.props(styles.heading)}>All Variants with Icons</h4>
+ <div {...stylex.props(styles.row)}>
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=52"
+ name="Positive"
+ size="large"
+ status={
+ <XDSAvatarStatusDot
+ variant="positive"
+ label="Verified"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=53"
+ name="Neutral"
+ size="large"
+ status={
+ <XDSAvatarStatusDot
+ variant="neutral"
+ label="Pending"
+ icon={<CheckIcon />}
+ />
+ }
+ />
+ <XDSAvatar
+ src="https://i.pravatar.cc/150?img=54"
+ name="Negative"
+ size="large"
+ status={
+ <XDSAvatarStatusDot
+ variant="negative"
+ label="Rejected"
+ icon={<CheckIcon />}
+ />
+ }
+ />
</div>
</div>
),
diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.md
index f65d9a65c5..e1b516b190 100644
--- a/packages/core/src/Avatar/README.md
+++ b/packages/core/src/Avatar/README.md
@@ -9,14 +9,15 @@ Avatar component for displaying user profile pictures with fallback support.
- **Image loading**: Primary and fallback image sources
- **Initials fallback**: Auto-generates initials from user name
- **Default icon**: Generic person icon when no image or name provided
-- **Sizes**: xsmall (24px), small (32px), medium (40px), large (56px), xlarge (80px)
+- **Sizes**: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values
- **Status slot**: Corner position for status indicators or badges
+- **Size-aware status dot**: Built-in `XDSAvatarStatusDot` that scales proportionally with avatar size
- **Accessible**: Proper role and aria-label support
## Usage
```tsx
-import { XDSAvatar } from '@xds/core/Avatar';
+import { XDSAvatar, XDSAvatarStatusDot } from '@xds/core/Avatar';
// With image
<XDSAvatar src="/user.jpg" name="John Doe" />
@@ -24,26 +25,52 @@ import { XDSAvatar } from '@xds/core/Avatar';
// Initials fallback
<XDSAvatar name="Jane Smith" size="large" />
-// With status indicator
-<XDSAvatar src="/user.jpg" status={<OnlineIndicator />} />
-
-// Different sizes
-<XDSAvatar name="AB" size="xsmall" />
-<XDSAvatar name="CD" size="medium" />
-<XDSAvatar name="EF" size="xlarge" />
+// With size-aware status indicator
+<XDSAvatar
+ src="/user.jpg"
+ name="John Doe"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}
+/>
+
+// Status dot scales automatically across sizes
+<XDSAvatar name="AB" size="tiny" status={<XDSAvatarStatusDot />} />
+<XDSAvatar name="CD" size="large" status={<XDSAvatarStatusDot />} />
+
+// Different variants for different contexts
+<XDSAvatar name="EF" status={<XDSAvatarStatusDot variant="negative" label="Busy" />} />
+<XDSAvatar name="GH" status={<XDSAvatarStatusDot variant="neutral" label="Away" />} />
```
## Props
-| Prop | Type | Default | Description |
-| ------------- | -------------------------------------------------------- | --------- | ------------------------------------ |
-| `src` | `string` | — | Primary image source URL |
-| `fallbackSrc` | `string` | — | Fallback image when primary fails |
-| `name` | `string` | — | User name for initials and alt text |
-| `alt` | `string` | — | Alt text (falls back to `name`) |
-| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'small'` | Avatar size |
-| `status` | `ReactNode` | — | Corner content for status indicators |
-| `data-testid` | `string` | — | Test ID for testing |
+### XDSAvatar
+
+| Prop | Type | Default | Description |
+| ------------- | --------------- | --------- | ------------------------------------ |
+| `src` | `string` | — | Primary image source URL |
+| `fallbackSrc` | `string` | — | Fallback image when primary fails |
+| `name` | `string` | — | User name for initials and alt text |
+| `alt` | `string` | — | Alt text (falls back to `name`) |
+| `size` | `XDSAvatarSize` | `'small'` | Avatar size (named or numeric) |
+| `status` | `ReactNode` | — | Corner content for status indicators |
+| `data-testid` | `string` | — | Test ID for testing |
+
+### XDSAvatarStatusDot
+
+| Prop | Type | Default | Description |
+| --------- | --------------------------------------- | ------------ | --------------------------------------------------- |
+| `variant` | `'positive' \| 'neutral' \| 'negative'` | `'positive'` | Semantic color variant of the dot |
+| `label` | `string` | — | Accessible label for screen readers |
+| `icon` | `ReactNode` | — | Icon centered inside the dot (hidden at tiny sizes) |
+
+The status dot reads the avatar size from context and uses discrete size tiers:
+
+| Avatar size | Dot size | Border |
+| ----------- | -------- | ------ |
+| ≤ 36px | 8px | 1px |
+| 40–72px | 16px | 2px |
+| ≥ 96px | 24px | 4px |
## Fallback Cascade
@@ -78,15 +105,17 @@ const theme: Theme = {
## Files
-| File | Role | Purpose |
-| -------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSAvatar.tsx` | Core | Component implementation |
-| `XDSAvatar.test.tsx` | Test | Unit tests |
+| File | Role | Purpose |
+| ------------------------- | -------- | ------------------------------------------ |
+| `index.ts` | Entry | Exports components and types |
+| `XDSAvatar.tsx` | Core | Avatar component implementation |
+| `XDSAvatarStatusDot.tsx` | Sub-comp | Size-aware status indicator dot |
+| `XDSAvatarSizeContext.ts` | Context | Internal context for passing size to slots |
## Implementation Notes
- Always circular shape (border-radius: 50%)
-- Size type derived from `keyof typeof sizes`
- Uses `color.deemphasized` and `color.textSecondary` for fallback background
- Initials extracted from first and last word of name
+- `XDSAvatarSizeContext` provides the resolved numeric size to sub-components
+- Status dot uses `CIRCLE_EDGE_OFFSET_RATIO` for positioning at the 45° point on the circle edge
diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsx
index 7f31ae6f64..7971a668d4 100644
--- a/packages/core/src/Avatar/XDSAvatar.tsx
+++ b/packages/core/src/Avatar/XDSAvatar.tsx
@@ -26,6 +26,7 @@ import {
} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {XDSAvatarSizeContext} from './XDSAvatarSizeContext';
/**
* The offset ratio for positioning elements on a circle's edge at 45°.
@@ -287,56 +288,59 @@ export const XDSAvatar = forwardRef<HTMLDivElement, XDSAvatarProps>(
const fallbackOverride = themeContext?.theme.components?.avatar?.fallback;
return (
- <div
- ref={ref}
- role="img"
- aria-label={accessibleName}
- data-testid={testId}
- {...stylex.props(styles.wrapper, rootOverride)}
- {...props}>
- <div {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
- {showImage && (
- <img
- src={src}
- alt={accessibleName}
- onError={() => setImageError(true)}
- {...stylex.props(styles.image)}
- />
- )}
- {showFallbackImage && (
- <img
- src={fallbackSrc}
- alt={accessibleName}
- onError={() => setFallbackError(true)}
- {...stylex.props(styles.image)}
- />
- )}
- {showInitials && (
+ <XDSAvatarSizeContext.Provider value={numericSize}>
+ <div
+ ref={ref}
+ role="img"
+ aria-label={accessibleName}
+ data-testid={testId}
+ {...stylex.props(styles.wrapper, rootOverride)}
+ {...props}>
+ <div
+ {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
+ {showImage && (
+ <img
+ src={src}
+ alt={accessibleName}
+ onError={() => setImageError(true)}
+ {...stylex.props(styles.image)}
+ />
+ )}
+ {showFallbackImage && (
+ <img
+ src={fallbackSrc}
+ alt={accessibleName}
+ onError={() => setFallbackError(true)}
+ {...stylex.props(styles.image)}
+ />
+ )}
+ {showInitials && (
+ <div
+ {...stylex.props(
+ styles.fallback,
+ dynamicStyles.fontSize(numericSize),
+ fallbackOverride,
+ )}>
+ {getInitials(name)}
+ </div>
+ )}
+ {showIcon && (
+ <div {...stylex.props(styles.fallback, fallbackOverride)}>
+ <DefaultIcon size={numericSize} />
+ </div>
+ )}
+ </div>
+ {status && (
<div
{...stylex.props(
- styles.fallback,
- dynamicStyles.fontSize(numericSize),
- fallbackOverride,
+ styles.status,
+ dynamicStyles.statusPosition(numericSize),
)}>
- {getInitials(name)}
- </div>
- )}
- {showIcon && (
- <div {...stylex.props(styles.fallback, fallbackOverride)}>
- <DefaultIcon size={numericSize} />
+ {status}
</div>
)}
</div>
- {status && (
- <div
- {...stylex.props(
- styles.status,
- dynamicStyles.statusPosition(numericSize),
- )}>
- {status}
- </div>
- )}
- </div>
+ </XDSAvatarSizeContext.Provider>
);
},
);
diff --git a/packages/core/src/Avatar/XDSAvatarSizeContext.ts b/packages/core/src/Avatar/XDSAvatarSizeContext.ts
new file mode 100644
index 0000000000..e02e34bc3a
--- /dev/null
+++ b/packages/core/src/Avatar/XDSAvatarSizeContext.ts
@@ -0,0 +1,19 @@
+/**
+ * @file XDSAvatarSizeContext.ts
+ * @input Uses React createContext
+ * @output Exports XDSAvatarSizeContext
+ * @position Internal context; provided by XDSAvatar, consumed by sub-components
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Avatar/README.md
+ */
+
+import {createContext} from 'react';
+
+/**
+ * Context that provides the resolved numeric avatar size (in pixels)
+ * to child components like XDSAvatarStatusDot.
+ *
+ * Default value of 36 matches the default 'small' avatar size.
+ */
+export const XDSAvatarSizeContext = createContext<number>(36);
diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
new file mode 100644
index 0000000000..e35dfdef72
--- /dev/null
+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
@@ -0,0 +1,182 @@
+/**
+ * @file XDSAvatarStatusDot.tsx
+ * @input Uses React, StyleX, theme tokens, and XDSAvatarSizeContext
+ * @output Exports XDSAvatarStatusDot component and XDSAvatarStatusDotProps type
+ * @position Sub-component of XDSAvatar; renders a size-aware status indicator
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Avatar/README.md (features, files table)
+ * - /packages/core/src/Avatar/index.ts (exports)
+ * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
+ */
+
+import {useContext, type HTMLAttributes, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {XDSAvatarSizeContext} from './XDSAvatarSizeContext';
+
+/**
+ * Resolves the status dot size, border width, and icon size based on the
+ * avatar size.
+ *
+ * Uses discrete size tiers rather than a continuous ratio so the dot
+ * looks intentional at every avatar size:
+ *
+ * | Avatar size | Dot | Border | Icon |
+ * |--------------|------|--------|------|
+ * | ≤ 36px | 8px | 1px | — |
+ * | 40–72px | 16px | 2px | 10px |
+ * | ≥ 96px | 24px | 4px | 14px |
+ *
+ * Icons are not rendered at the smallest tier — there isn't enough
+ * room for them to be legible.
+ */
+function resolveStatusDotSize(avatarSize: number): {
+ dotSize: number;
+ borderWidth: number;
+ iconSize: number;
+} {
+ if (avatarSize <= 36) {
+ return {dotSize: 8, borderWidth: 1, iconSize: 0};
+ }
+ if (avatarSize <= 72) {
+ return {dotSize: 16, borderWidth: 2, iconSize: 10};
+ }
+ return {dotSize: 24, borderWidth: 4, iconSize: 14};
+}
+
+export type XDSAvatarStatusDotVariant = 'positive' | 'neutral' | 'negative';
+
+export interface XDSAvatarStatusDotProps extends Omit<
+ HTMLAttributes<HTMLDivElement>,
+ 'children'
+> {
+ /**
+ * The semantic color variant of the dot.
+ * - `positive` — green dot (e.g. online, accepted)
+ * - `neutral` — gray dot (e.g. offline, pending)
+ * - `negative` — red dot (e.g. busy, rejected)
+ *
+ * Matches the `variant` convention from `XDSStatusDot`.
+ * @default 'positive'
+ */
+ variant?: XDSAvatarStatusDotVariant;
+ /**
+ * Accessible label for the status dot.
+ * Describes the meaning of the indicator for screen readers
+ * (e.g. "Online", "Accepted", "John Doe is busy").
+ */
+ label?: string;
+ /**
+ * Optional icon to render centered inside the dot.
+ * Accepts any ReactNode (typically an SVG icon).
+ * The icon is automatically sized to fit the dot and hidden
+ * at the smallest avatar sizes where there isn't enough room.
+ *
+ * @example
+ * ```tsx
+ * <XDSAvatarStatusDot variant="positive" label="Verified" icon={<CheckIcon />} />
+ * ```
+ */
+ icon?: ReactNode;
+}
+
+const styles = stylex.create({
+ dot: {
+ borderRadius: '50%',
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-surface'],
+ boxSizing: 'border-box',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+ positive: {
+ backgroundColor: colorVars['--color-positive'],
+ },
+ neutral: {
+ backgroundColor: colorVars['--color-text-secondary'],
+ },
+ negative: {
+ backgroundColor: colorVars['--color-negative'],
+ },
+ icon: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ color: colorVars['--color-surface'],
+ lineHeight: 0,
+ },
+});
+
+const dynamicStyles = stylex.create({
+ size: (dotSize: number, borderWidth: number) => ({
+ width: dotSize,
+ height: dotSize,
+ borderWidth,
+ }),
+ iconSize: (size: number) => ({
+ width: size,
+ height: size,
+ }),
+});
+
+const variantStyleMap: Record<XDSAvatarStatusDotVariant, stylex.StyleXStyles> =
+ {
+ positive: styles.positive,
+ neutral: styles.neutral,
+ negative: styles.negative,
+ };
+
+/**
+ * A status indicator dot that automatically scales to match the parent
+ * XDSAvatar's size.
+ *
+ * Must be used inside an XDSAvatar's `status` prop so it can read
+ * the avatar size from context.
+ *
+ * @example
+ * ```tsx
+ * // Presence indicator
+ * <XDSAvatar
+ * name="John Doe"
+ * size="medium"
+ * status={<XDSAvatarStatusDot variant="positive" label="Online" />}
+ * />
+ *
+ * // With icon (e.g. verified badge)
+ * <XDSAvatar
+ * name="Jane Smith"
+ * size="large"
+ * status={<XDSAvatarStatusDot variant="positive" label="Verified" icon={<CheckIcon />} />}
+ * />
+ * ```
+ */
+export function XDSAvatarStatusDot({
+ variant = 'positive',
+ label,
+ icon,
+ ...props
+}: XDSAvatarStatusDotProps) {
+ const avatarSize = useContext(XDSAvatarSizeContext);
+ const {dotSize, borderWidth, iconSize} = resolveStatusDotSize(avatarSize);
+
+ return (
+ <div
+ {...(label ? {'aria-label': label} : undefined)}
+ {...stylex.props(
+ styles.dot,
+ variantStyleMap[variant],
+ dynamicStyles.size(dotSize, borderWidth),
+ )}
+ {...props}>
+ {icon && iconSize > 0 && (
+ <span
+ aria-hidden="true"
+ {...stylex.props(styles.icon, dynamicStyles.iconSize(iconSize))}>
+ {icon}
+ </span>
+ )}
+ </div>
+ );
+}
diff --git a/packages/core/src/Avatar/index.ts b/packages/core/src/Avatar/index.ts
index bef4323f25..769a552653 100644
--- a/packages/core/src/Avatar/index.ts
+++ b/packages/core/src/Avatar/index.ts
@@ -1,7 +1,7 @@
/**
* @file index.ts
- * @input Imports XDSAvatar component and types from XDSAvatar.tsx
- * @output Exports XDSAvatar, XDSAvatarProps, XDSAvatarSize
+ * @input Imports XDSAvatar component and types from XDSAvatar.tsx, XDSAvatarStatusDot from XDSAvatarStatusDot.tsx
+ * @output Exports XDSAvatar, XDSAvatarProps, XDSAvatarSize, XDSAvatarStatusDot, XDSAvatarStatusDotProps, XDSAvatarStatusDotVariant
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
* SYNC: When modified, update this header and /packages/core/src/Avatar/README.md
@@ -9,3 +9,8 @@
export {XDSAvatar} from './XDSAvatar';
export type {XDSAvatarProps, XDSAvatarSize} from './XDSAvatar';
+export {XDSAvatarStatusDot} from './XDSAvatarStatusDot';
+export type {
+ XDSAvatarStatusDotProps,
+ XDSAvatarStatusDotVariant,
+} from './XDSAvatarStatusDot';