@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/Avatar/Avatar.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Avatar.tsx
- * @input Uses React, HTMLAttributes, ReactNode, useState; useTooltip
+ * @input Uses React, HTMLAttributes, ReactNode, useState, useRef; useTooltip
  *   (Tooltip hook) for the optional name-on-hover tooltip; useTranslator (i18n)
  * @output Exports Avatar component, AvatarProps, AvatarSize types
  * @position Core implementation; consumed by index.ts
@@ -12,13 +12,14 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Avatar/index.ts (exports if types change)
+ * - /packages/core/src/Avatar/AvatarStatusLabelContext.ts (the status label ref)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  *
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
 
-import {isValidElement, useMemo, useState, type ReactNode} from 'react';
+import {isValidElement, useMemo, useRef, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -28,6 +29,10 @@ import {
   radiusVars,
 } from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
+import {
+  AvatarStatusLabelContext,
+  type AvatarStatusLabelTarget,
+} from './AvatarStatusLabelContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
@@ -37,7 +42,7 @@ import {useTooltip} from '../Tooltip/useTooltip';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
-import {useTranslator} from '../i18n';
+import {useTranslator, type TranslatorFn} from '../i18n';
 
 /**
  * The offset ratio for positioning elements on a circle's edge at 45°.
@@ -170,7 +175,10 @@ const styles = stylex.create({
     color: 'inherit',
     font: 'inherit',
     textDecoration: 'none',
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     // Match the avatar's circular shape so the focus ring hugs it.
     borderRadius: radiusVars['--radius-full'],
   },
@@ -268,10 +276,14 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    * Content displayed in the corner of the avatar.
    * Typically used for status indicators or badges.
    *
-   * When the element carries a string `label` prop (as `AvatarStatusDot`
-   * does), the label is composed into the avatar's accessible name
-   * (e.g. "Jane Doe, Online") so assistive tech can reach the status —
-   * the `role="img"` root prunes descendant semantics (WCAG 4.1.2).
+   * `AvatarStatusDot` reports its own `label` to the avatar, which composes
+   * it into the avatar's accessible name (e.g. "Jane Doe, Online") so
+   * assistive tech can reach the status: the `role="img"` root prunes
+   * descendant semantics (WCAG 4.1.2). Reporting goes through context, so it
+   * still works when the dot sits inside a wrapper component of your own. A
+   * custom status element that is not an `AvatarStatusDot` names itself the
+   * same way, by rendering an `AvatarStatusDot` or by carrying a string
+   * `label` prop.
    */
   status?: ReactNode;
   /**
@@ -342,13 +354,13 @@ function getInitials(name: string): string {
 
 /**
  * Reads the accessible status label off the `status` element, when it
- * exposes one. `AvatarStatusDot`'s `label` prop is the canonical source,
- * but any custom status element with a string `label` prop participates.
+ * exposes one.
  *
- * The avatar root is `role="img"`, which prunes ALL descendant semantics
- * from the accessibility tree — a label inside the status subtree is never
- * announced on its own. Composing it into the avatar's own accessible name
- * is the only way the status reaches assistive tech (WCAG 4.1.2).
+ * Only sees a literal `label` prop on the element the consumer passes, so a
+ * consumer's own wrapper around the dot hides it — that case comes in through
+ * `AvatarStatusLabelContext` instead. Kept because it answers the first
+ * render, before any report has landed, and because it tracks a label that
+ * changes on an element that does not report at all.
  */
 function getStatusLabel(status: ReactNode): string | undefined {
   if (!isValidElement(status)) {
@@ -358,6 +370,68 @@ function getStatusLabel(status: ReactNode): string | undefined {
   return typeof label === 'string' && label !== '' ? label : undefined;
 }
 
+/**
+ * The string when it carries something, `undefined` when it is absent or
+ * blank. An empty accessible name is meaningless, so a blank reads as
+ * absent, the way Icon treats `label=""`.
+ */
+function meaningful(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+
+/**
+ * Derives the root's ARIA attributes from the resolved accessible name,
+ * following Icon's `getIconA11yProps`.
+ *
+ * - A name → meaningful image: `role="img"` + `aria-label`.
+ * - No name → decorative: `role="presentation"` + `aria-hidden="true"`, rather
+ *   than announcing a meaningless generic "Avatar" (obs-9).
+ *
+ * The result is spread BEFORE `{...props}` on every root so an explicit
+ * `aria-label` / `role` / `aria-hidden` from the consumer always wins.
+ */
+function getAvatarA11yProps(
+  accessibleName: string | undefined,
+):
+  | {role: 'img'; 'aria-label': string}
+  | {role: 'presentation'; 'aria-hidden': 'true'} {
+  return accessibleName != null && accessibleName !== ''
+    ? {role: 'img', 'aria-label': accessibleName}
+    : {role: 'presentation', 'aria-hidden': 'true'};
+}
+
+/**
+ * The avatar's accessible name: its own name, the status label, or the two
+ * composed ("Jane Doe, Online"). Used both by render and by the commit-phase
+ * update, so the two can never compose differently.
+ */
+function composeAccessibleName(
+  t: TranslatorFn,
+  nameLabel: string | undefined,
+  statusLabel: string | undefined,
+): string | undefined {
+  if (nameLabel && statusLabel) {
+    return t('@astryx.avatar.nameWithStatus', {
+      name: nameLabel,
+      status: statusLabel,
+    });
+  }
+  return nameLabel || statusLabel;
+}
+
+/** Sets an attribute, or removes it when the value is absent. */
+function setAttributeOrRemove(
+  element: HTMLElement,
+  name: string,
+  value: string | undefined,
+): void {
+  if (value == null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+
 /**
  * Default person icon SVG for when no image or name is provided
  */
@@ -424,8 +498,8 @@ export function Avatar({
   // A whitespace-only string carries no identity. Without this it produces no
   // initials (getInitials trims to nothing) and no default icon (a space is
   // truthy), leaving an empty plate behind a blank accessible name.
-  const meaningfulName = name?.trim() ? name : undefined;
-  const meaningfulAlt = alt?.trim() ? alt : undefined;
+  const meaningfulName = meaningful(name);
+  const meaningfulAlt = meaningful(alt);
   const showInitials = !showImage && !showFallbackImage && meaningfulName;
   const showIcon = !showImage && !showFallbackImage && !meaningfulName;
 
@@ -439,15 +513,21 @@ export function Avatar({
   // generic "Avatar" (obs-9).
   const t = useTranslator();
   const nameLabel = meaningfulAlt || meaningfulName;
-  const statusLabel = getStatusLabel(status);
-  const accessibleName =
-    nameLabel && statusLabel
-      ? t('@astryx.avatar.nameWithStatus', {
-          name: nameLabel,
-          status: statusLabel,
-        })
-      : nameLabel || statusLabel;
-  const isDecorative = !accessibleName;
+  // This render can only see a label introspected off a directly-passed
+  // element. A status inside a consumer's own wrapper reports through the ref
+  // below, in the commit phase, and lands on the root element from there.
+  const accessibleName = composeAccessibleName(
+    t,
+    nameLabel,
+    getStatusLabel(status),
+  );
+  const a11yProps = getAvatarA11yProps(accessibleName);
+  // An `<a>`/`<button>` root carries its own role and must not be hidden, so
+  // only the name transfers. Spread before `{...props}` for the same
+  // consumer-wins precedence as the static root.
+  const a11yLabelProps = accessibleName
+    ? {'aria-label': accessibleName}
+    : undefined;
   const avatarGroup = useAvatarGroup();
   const resolvedSize = avatarGroup?.size ?? size;
   const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);
@@ -484,8 +564,8 @@ export function Avatar({
     isEnabled: showTooltip,
   });
   // The tooltip ref attaches to whichever root element renders (static or
-  // interactive), so the tooltip works for link/button avatars too.
-  const rootRef = mergeRefs(ref, showTooltip ? tooltipHook.ref : undefined);
+  // interactive), so the tooltip works for link/button avatars too. The root
+  // ref itself is assembled below, once the element swap is resolved.
   const describedByProp =
     showTooltip && isCustomTooltip
       ? {
@@ -504,14 +584,74 @@ export function Avatar({
   const isInteractive = renderAsLink || renderAsButton;
   const LinkComponent = useLinkComponent(as);
 
-  // An interactive control with no accessible name is an unacceptable control
-  // name. `useDevWarning` is the shared guardrail: it warns once per mount
-  // rather than on every render, and compiles out of production builds.
+  // An interactive control needs an identity of its own. A status label is not
+  // one: it composes into the accessible name, so `<Avatar href status={<dot
+  // label="Online" />} />` resolves a name that reads as legitimate and says
+  // nothing about who the link points at. Only `alt`/`name` count, or a
+  // consumer's own `aria-label`/`aria-labelledby` escape hatch, which wins
+  // over the derived props below.
+  const consumerName =
+    meaningful(props['aria-label']) ?? meaningful(props['aria-labelledby']);
   useDevWarning(
     'Avatar',
     'an interactive avatar (with `href` or `onClick`) needs a meaningful ' +
       'accessible name. Pass `alt` or `name`.',
-    isInteractive && !accessibleName,
+    isInteractive && !nameLabel && consumerName == null,
+  );
+
+  // A status inside a consumer's own wrapper is invisible to render: the dot
+  // writes its label into this ref from its own callback ref, in the commit
+  // phase. A ref write cannot re-render, so the composed name is written
+  // straight onto the root element instead — still before paint, and with no
+  // second render.
+  const statusLabelRef = useRef<AvatarStatusLabelTarget>({
+    label: undefined,
+    update: null,
+  });
+  // A fresh callback ref every render, so React reattaches it on every commit
+  // and the name is recomposed after React has written this render's props.
+  // `update` covers the other direction: a label that changes while the avatar
+  // itself does not re-render.
+  const nameRef = (element: HTMLElement | null) => {
+    if (element == null) {
+      return;
+    }
+    const target = statusLabelRef.current;
+    target.update = () => {
+      const composed = composeAccessibleName(
+        t,
+        nameLabel,
+        meaningful(target.label) ?? getStatusLabel(status),
+      );
+      // A consumer's own ARIA wins here exactly as it does in render, where
+      // the derived props spread before `{...props}`.
+      if (props['aria-label'] == null) {
+        setAttributeOrRemove(element, 'aria-label', composed);
+      }
+      // An `<a>`/`<button>` root carries its own role and must not be hidden,
+      // so only the name transfers there.
+      if (!isInteractive) {
+        if (props.role == null) {
+          element.setAttribute('role', composed ? 'img' : 'presentation');
+        }
+        if (props['aria-hidden'] == null) {
+          setAttributeOrRemove(
+            element,
+            'aria-hidden',
+            composed ? undefined : 'true',
+          );
+        }
+      }
+    };
+    target.update();
+    return () => {
+      target.update = null;
+    };
+  };
+  const rootRef = mergeRefs(
+    ref,
+    showTooltip ? tooltipHook.ref : undefined,
+    nameRef,
   );
 
   // The inner visuals are identical across the static and interactive variants.
@@ -601,13 +741,13 @@ export function Avatar({
     // it up while ignoring nested buttons in a custom status/badge slot.
     rootElement = (
       <LinkComponent
+        {...a11yLabelProps}
         {...interactivePassthrough}
         {...describedByProp}
         ref={rootRef as React.Ref<HTMLAnchorElement>}
         href={href}
         target={target}
         rel={rel}
-        aria-label={accessibleName}
         data-avatar-item=""
         data-testid={testId}
         onClick={onClick}
@@ -618,11 +758,11 @@ export function Avatar({
   } else if (renderAsButton) {
     rootElement = (
       <button
+        {...a11yLabelProps}
         {...interactivePassthrough}
         {...describedByProp}
         ref={rootRef}
         type="button"
-        aria-label={accessibleName}
         data-avatar-item=""
         data-testid={testId}
         onClick={onClick}
@@ -633,11 +773,9 @@ export function Avatar({
   } else {
     rootElement = (
       <div
+        {...a11yProps}
         {...props}
         ref={rootRef}
-        role={isDecorative ? 'presentation' : 'img'}
-        aria-label={isDecorative ? undefined : accessibleName}
-        aria-hidden={isDecorative || undefined}
         // The root is a div[role="img"], not natively focusable. When a name
         // tooltip is active, add a tab stop so keyboard users can reveal it
         // (WCAG 1.4.13 / 2.1.1) — matching Timestamp/Button. Suppressed inside
@@ -652,7 +790,11 @@ export function Avatar({
   }
 
   const avatarElement = (
-    <AvatarSizeContext value={numericSize}>{rootElement}</AvatarSizeContext>
+    <AvatarSizeContext value={numericSize}>
+      <AvatarStatusLabelContext value={statusLabelRef}>
+        {rootElement}
+      </AvatarStatusLabelContext>
+    </AvatarSizeContext>
   );
 
   // Always return the same structure so the avatar keeps its position in the

package/src/Avatar/AvatarStatusDot.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file AvatarStatusDot.tsx
- * @input Uses React, StyleX, theme tokens, and AvatarSizeContext
+ * @input Uses React, StyleX, theme tokens, AvatarSizeContext, and
+ *   AvatarStatusLabelContext (label reporting)
  * @output Exports AvatarStatusDot component and AvatarStatusDotProps type
  * @position Sub-component of Avatar; renders a size-aware status indicator
  *
@@ -15,12 +16,13 @@
  * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  */
 
-import React, {use, type ReactNode} from 'react';
+import React, {use, useCallback, useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
-import {isRenderable, mergeProps} from '../utils';
+import {AvatarStatusLabelContext} from './AvatarStatusLabelContext';
+import {isRenderable, mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {AvatarStatusDotVariantMap} from './index';
 
@@ -311,6 +313,30 @@ export function AvatarStatusDot({
   ...props
 }: AvatarStatusDotProps) {
   const avatarSize = use(AvatarSizeContext);
+  const statusLabelRef = use(AvatarStatusLabelContext);
+  // Report the label through the avatar's ref from a callback ref rather than
+  // an Effect: the ref runs in the commit phase, so the avatar's accessible
+  // name is composed before paint, and a ref write costs no render.
+  /* eslint-disable react-compiler/react-compiler -- the avatar shares its own
+     ref through context so the dot can write into it; a context read looks
+     immutable to the compiler */
+  const reportRef = useCallback(() => {
+    const target = statusLabelRef?.current;
+    if (target == null) {
+      return;
+    }
+    target.label = label;
+    target.update?.();
+    return () => {
+      target.label = undefined;
+      target.update?.();
+    };
+  }, [statusLabelRef, label]);
+  /* eslint-enable react-compiler/react-compiler */
+  // Memoized so React only detaches and reattaches when the reported label
+  // actually changes; an inline merge would withdraw and re-report on every
+  // render of the avatar.
+  const rootRef = useMemo(() => mergeRefs(ref, reportRef), [ref, reportRef]);
   const {dotSize, borderWidth, iconSize, tier} =
     resolveStatusDotSize(avatarSize);
   const showsIcon = isRenderable(icon) && iconSize > 0;
@@ -321,7 +347,7 @@ export function AvatarStatusDot({
   return (
     <div
       {...props}
-      ref={ref}
+      ref={rootRef}
       {...(label ? {role: 'img', 'aria-label': label} : undefined)}
       {...mergeProps(
         themeProps('avatar-status-dot', {variant}),

package/src/Avatar/AvatarStatusLabelContext.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AvatarStatusLabelContext.ts
+ * @input Uses React createContext, RefObject
+ * @output Exports AvatarStatusLabelContext, AvatarStatusLabelTarget
+ * @position Internal context; provided by Avatar, consumed by AvatarStatusDot
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Avatar/Avatar.doc.mjs
+ */
+
+import {createContext, type RefObject} from 'react';
+
+/**
+ * The box a status element writes its label into.
+ *
+ * `update` is the avatar's own recompose, set while its root element is
+ * attached and null otherwise. Writing `label` alone is enough on mount (the
+ * avatar reads the box when its root attaches, which happens after its
+ * children's refs); calling `update` covers a label that changes later
+ * without the avatar itself re-rendering.
+ */
+export interface AvatarStatusLabelTarget {
+  label: string | undefined;
+  update: (() => void) | null;
+}
+
+/**
+ * Lets a status element hand its accessible label to the enclosing Avatar,
+ * which composes it into its own accessible name ("Jane Doe, Online").
+ *
+ * The avatar root is `role="img"`, which prunes all descendant semantics, so
+ * composing the label in is the only way the status reaches assistive tech
+ * (WCAG 4.1.2). Reading `label` off the passed element only works when the
+ * consumer passes `AvatarStatusDot` directly; this route works through a
+ * consumer's own wrapper, at any depth.
+ *
+ * The value is a ref, written from the dot's own callback ref in the commit
+ * phase, so reporting a label costs no render and no state. `null` outside an
+ * Avatar, where a standalone dot names itself and has nobody to report to.
+ */
+export const AvatarStatusLabelContext =
+  createContext<RefObject<AvatarStatusLabelTarget> | null>(null);
+AvatarStatusLabelContext.displayName = 'AvatarStatusLabelContext';

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -11,11 +11,12 @@ export const docs = {
     description:
       'AvatarGroup displays multiple avatars in an overlapping row with an optional overflow indicator. Uses a compositional API: pass Avatar children directly so each avatar can carry its own props (status dots, click handlers, etc.).',
     bestPractices: [
-      {guidance: true, description: 'Set max to limit visible avatars when the list is long; 3-5 is typical.'},
+      {guidance: true, description: 'Slice the list yourself and pass only the avatars you want visible; 3-5 is typical. The group renders exactly the children it is given and never slices for you.'},
       {guidance: true, description: 'Use AvatarGroupOverflow for custom overflow content like a popover trigger or "add member" button.'},
       {guidance: true, description: 'Pass status dots, click handlers, or tooltips directly on each Avatar child.'},
-      {guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech.'},
+      {guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech. This follows the WAI-ARIA APG roving tabindex technique for managing focus in a composite: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
       {guidance: false, description: "Don't nest AvatarGroups; use a single group with all avatars."},
+      {guidance: false, description: "Don't set size on the child avatars. The group's size wins over each child's own size prop, including when the group leaves size at its default, so a child's size is silently ignored inside a group."},
     ],
     anatomy: [
       {name: 'Avatar children', required: true, description: 'Avatar elements that form the overlapping row. Each can have its own props.'},
@@ -47,7 +48,8 @@ export const docs = {
     {
       name: 'size',
       type: 'AvatarSize',
-      description: 'Size applied to all avatars via context.',
+      description:
+        "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
       default: "'md'",
     },
     {
@@ -77,10 +79,11 @@ export const docsZh = {
     description:
       'AvatarGroup 以重叠排列方式显示多个头像，并可选择显示溢出指示器。使用组合式 API：直接传入 Avatar 子元素，每个头像可携带自己的属性。',
     bestPractices: [
-      {guidance: true, description: '当列表较长时设置 max 来限制可见头像数量，通常 3-5 个为佳。'},
+      {guidance: true, description: '自行切分列表，只传入需要显示的头像，通常 3-5 个为佳。组件只渲染传入的子元素，不会自动切分。'},
       {guidance: true, description: '使用 AvatarGroupOverflow 自定义溢出内容，如弹出触发器或"添加成员"按钮。'},
       {guidance: true, description: '直接在每个 Avatar 子元素上传递状态点、点击处理器或工具提示。'},
       {guidance: false, description: '不要嵌套 AvatarGroup，使用单个组包含所有头像。'},
+      {guidance: false, description: '不要在子头像上设置 size。分组的 size 会覆盖每个子 Avatar 自身的 size，即使分组使用默认值也是如此。'},
     ],
   },
 };
@@ -92,11 +95,12 @@ export const docsDense = {
     description:
       'Stacked avatar display with overlapping layout. Compositional API: Avatar children with per-avatar props (status dots, clicks). Optional AvatarGroupOverflow slot for custom overflow.',
     bestPractices: [
-      {guidance: true, description: 'Set max to limit visible avatars (3-5 typical).'},
+      {guidance: true, description: 'Slice the list yourself; pass only visible avatars (3-5 typical). No auto-slicing.'},
       {guidance: true, description: 'Use AvatarGroupOverflow for custom overflow (popover, add button).'},
       {guidance: true, description: 'Pass status dots / click handlers directly on each Avatar.'},
-      {guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button (APG roving tabindex).'},
       {guidance: false, description: "Don't nest AvatarGroups."},
+      {guidance: false, description: "Don't set size on children; the group's size always wins, default included."},
     ],
   },
 };

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -231,6 +231,31 @@ describe('AvatarGroupOverflow — hardening', () => {
     expect(screen.getByLabelText('0 more')).toBeInTheDocument();
   });
 
+  it('clamps a negative count rather than rendering "+-3"', () => {
+    // `count={total - visibleCount}` is the documented shape, and it goes
+    // negative whenever the list is shorter than the slice.
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={-3} />
+      </AvatarGroup>,
+    );
+
+    expect(screen.queryByText('+-3')).not.toBeInTheDocument();
+    expect(screen.getByText('+0')).toBeInTheDocument();
+    expect(screen.getByLabelText('0 more')).toBeInTheDocument();
+  });
+
+  it('renders outside an AvatarGroup at the md fallback size', () => {
+    render(<AvatarGroupOverflow count={3} data-testid="loose" />);
+
+    const overflow = screen.getByTestId('loose');
+    expect(overflow).toHaveTextContent('+3');
+    // inline-flex, so a standalone indicator stays a circle instead of
+    // stretching to its parent's width.
+    expect(overflow.tagName).toBe('SPAN');
+  });
+
   it('handles very large count', () => {
     render(
       <AvatarGroup>
@@ -400,3 +425,40 @@ describe('AvatarGroup — roving focus + keyboard hint', () => {
     expect(screen.getByTestId('bob')).not.toHaveAttribute('tabindex');
   });
 });
+
+describe('AvatarGroup — size cascade', () => {
+  const sizeClasses = (el: HTMLElement) => el.className.split(/\s+/);
+
+  it("the group's size overrides a child's own size prop", () => {
+    render(
+      <AvatarGroup size="lg">
+        <Avatar name="Alice" size="xsm" data-testid="alice" />
+      </AvatarGroup>,
+    );
+
+    const classes = sizeClasses(screen.getByTestId('alice'));
+    expect(classes).toContain('lg');
+    expect(classes).not.toContain('xsm');
+  });
+
+  it("the group's default size also overrides a child's own size prop", () => {
+    // Known open finding: the group always publishes a size on its context, so
+    // a group that never set one still imposes md on children that did set one.
+    // Pinned here so the behaviour cannot change without a deliberate edit.
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" size="xl" data-testid="alice" />
+      </AvatarGroup>,
+    );
+
+    const classes = sizeClasses(screen.getByTestId('alice'));
+    expect(classes).toContain('md');
+    expect(classes).not.toContain('xl');
+  });
+
+  it("outside a group the avatar's own size applies", () => {
+    render(<Avatar name="Alice" size="xl" data-testid="alice" />);
+
+    expect(sizeClasses(screen.getByTestId('alice'))).toContain('xl');
+  });
+});

package/src/AvatarGroup/AvatarGroup.tsx

@@ -48,7 +48,9 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
    */
   children: ReactNode;
   /**
-   * Size applied to all avatars via context.
+   * Size applied to all avatars via context. This wins over each child
+   * Avatar's own `size` prop, including when it is left at the default, so
+   * set the size here rather than on the children.
    * @default 'md'
    */
   size?: AvatarSize;