@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Avatar/AvatarStatusDot.test.tsx

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {Avatar} from './Avatar';
+import {AvatarStatusDot, type AvatarStatusDotVariant} from './AvatarStatusDot';
+
+const GLYPH_SELECTOR = '.astryx-avatar-status-dot-glyph';
+const DOT_SELECTOR = '.astryx-avatar-status-dot';
+
+/**
+ * Renders an AvatarStatusDot inside an Avatar of the given numeric size and
+ * returns the dot root element. Size tiers: <=36 -> 10px dot (no icons),
+ * 40-72 -> 20px dot, >=96 -> 32px dot.
+ */
+function renderDot(
+  dotProps: React.ComponentProps<typeof AvatarStatusDot>,
+  avatarSize: 36 | 48 | 128 = 48,
+) {
+  const {container} = render(
+    <Avatar
+      name="Ada Lovelace"
+      size={avatarSize}
+      status={<AvatarStatusDot {...dotProps} />}
+    />,
+  );
+  const dot = container.querySelector(DOT_SELECTOR);
+  expect(dot).not.toBeNull();
+  return dot as HTMLElement;
+}
+
+describe('AvatarStatusDot', () => {
+  describe('shape glyphs (WCAG 1.4.1 — colour is not the only signal)', () => {
+    it('renders no glyph for success: the plain filled dot is the reference shape', () => {
+      const dot = renderDot({variant: 'success'});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+
+    it('renders a ring glyph for neutral', () => {
+      const dot = renderDot({variant: 'neutral'});
+      const glyph = dot.querySelector(GLYPH_SELECTOR);
+      expect(glyph).not.toBeNull();
+      expect(glyph).toHaveAttribute('data-shape', 'ring');
+    });
+
+    it('renders a minus glyph for error', () => {
+      const dot = renderDot({variant: 'error'});
+      const glyph = dot.querySelector(GLYPH_SELECTOR);
+      expect(glyph).not.toBeNull();
+      expect(glyph).toHaveAttribute('data-shape', 'minus');
+    });
+
+    it('hides the glyph from assistive tech: it is a visual redundancy of the status', () => {
+      const dot = renderDot({variant: 'error'});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it('renders glyphs at every size tier', () => {
+      for (const size of [36, 48, 128] as const) {
+        const dot = renderDot({variant: 'neutral'}, size);
+        expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+      }
+    });
+
+    it('draws the glyph as an inline svg sized to the dot inner field', () => {
+      // The glyph is a stroked <svg>, matching how the rest of the system
+      // draws marks (Icon's defaultIcons, the CheckboxInput checkmark).
+      // Its viewBox is 1 user unit per px of the dot's inner field
+      // (dot minus both borders), so stroke widths below are literal px.
+      const cases = [
+        [36, 8],
+        [48, 16],
+        [128, 24],
+      ] as const;
+      for (const [avatarSize, field] of cases) {
+        const glyph = renderDot({variant: 'neutral'}, avatarSize).querySelector(
+          GLYPH_SELECTOR,
+        ) as SVGElement;
+        expect(glyph.tagName.toLowerCase(), `avatar ${avatarSize}`).toBe('svg');
+        expect(glyph.getAttribute('viewBox'), `avatar ${avatarSize}`).toBe(
+          `0 0 ${field} ${field}`,
+        );
+        expect(glyph.getAttribute('width'), `avatar ${avatarSize}`).toBe(
+          String(field),
+        );
+        expect(glyph.getAttribute('height'), `avatar ${avatarSize}`).toBe(
+          String(field),
+        );
+      }
+    });
+
+    it('strokes the ring at the system glyph weight, not a quarter of the field', () => {
+      // stroke ~= field / 12, floored at 1px for the smallest tier, which
+      // puts these on the icon family's 1 / 1.5 / 2 ladder (~6-12% of the
+      // field) instead of the 25% band a CSS box cutout produced.
+      const cases = [
+        // avatar size, field, stroke, radius = (field - stroke) / 2
+        [36, 8, 1, 3.5],
+        [48, 16, 1.5, 7.25],
+        [128, 24, 2, 11],
+      ] as const;
+      for (const [avatarSize, field, stroke, radius] of cases) {
+        const circle = renderDot(
+          {variant: 'neutral'},
+          avatarSize,
+        ).querySelector(`${GLYPH_SELECTOR} circle`) as SVGCircleElement;
+        expect(circle, `avatar ${avatarSize}`).not.toBeNull();
+        expect(
+          circle.getAttribute('stroke-width'),
+          `avatar ${avatarSize}`,
+        ).toBe(String(stroke));
+        // Radius is to the stroke centreline, so the ring's outer edge lands
+        // exactly on the inner field and never clips against the border.
+        expect(circle.getAttribute('r'), `avatar ${avatarSize}`).toBe(
+          String(radius),
+        );
+        expect(circle.getAttribute('cx'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(circle.getAttribute('cy'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(circle.getAttribute('fill'), `avatar ${avatarSize}`).toBe(
+          'none',
+        );
+      }
+    });
+
+    it('strokes the minus bar at the same weight, spanning 75% of the field with round caps', () => {
+      // Ends are inset by half the stroke so the round caps land inside the
+      // 75% span rather than overhanging it.
+      const cases = [
+        // avatar size, field, stroke, x1, x2
+        [36, 8, 1, 1.5, 6.5],
+        [48, 16, 1.5, 2.75, 13.25],
+        [128, 24, 2, 4, 20],
+      ] as const;
+      for (const [avatarSize, field, stroke, x1, x2] of cases) {
+        const line = renderDot({variant: 'error'}, avatarSize).querySelector(
+          `${GLYPH_SELECTOR} line`,
+        ) as SVGLineElement;
+        expect(line, `avatar ${avatarSize}`).not.toBeNull();
+        expect(line.getAttribute('stroke-width'), `avatar ${avatarSize}`).toBe(
+          String(stroke),
+        );
+        expect(line.getAttribute('x1'), `avatar ${avatarSize}`).toBe(
+          String(x1),
+        );
+        expect(line.getAttribute('x2'), `avatar ${avatarSize}`).toBe(
+          String(x2),
+        );
+        expect(line.getAttribute('y1'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(line.getAttribute('y2'), `avatar ${avatarSize}`).toBe(
+          String(field / 2),
+        );
+        expect(
+          line.getAttribute('stroke-linecap'),
+          `avatar ${avatarSize}`,
+        ).toBe('round');
+      }
+    });
+
+    it('paints both glyphs from currentColor so the dot owns the ink colour', () => {
+      for (const variant of ['neutral', 'error'] as const) {
+        const mark = renderDot({variant}, 48).querySelector(
+          `${GLYPH_SELECTOR} circle, ${GLYPH_SELECTOR} line`,
+        ) as SVGElement;
+        expect(mark.getAttribute('stroke'), variant).toBe('currentColor');
+      }
+    });
+
+    it('fills the ring variant with surface and inks it with the variant colour', () => {
+      // A ring only reads as hollow if its interior is not the variant
+      // colour, so `neutral` inverts: surface fill, coloured stroke.
+      // StyleX atomic classes are deterministic, so a local probe pins it.
+      const probe = stylex.create({
+        ring: {
+          backgroundColor: colorVars['--color-background-surface'],
+          color: colorVars['--color-text-secondary'],
+        },
+      });
+      const dot = renderDot({variant: 'neutral'}, 48);
+      const atomicClasses = (stylex.props(probe.ring).className ?? '')
+        .split(' ')
+        // Dev mode prepends a per-file `File__style.key` debug class that
+        // legitimately differs between the probe and the component.
+        .filter(cls => !cls.includes('__'));
+      expect(atomicClasses.length).toBeGreaterThan(0);
+      for (const cls of atomicClasses) {
+        expect(dot.className).toContain(cls);
+      }
+    });
+
+    it('lets a user icon inherit the dot ink instead of hard-coding surface', () => {
+      // Surface ink on the surface-filled ring variant would be invisible.
+      const probe = stylex.create({
+        surfaceInk: {color: colorVars['--color-background-surface']},
+      });
+      renderDot(
+        {variant: 'neutral', icon: <svg data-testid="user-icon" />},
+        48,
+      );
+      const iconWrapper = screen.getByTestId('user-icon')
+        .parentElement as HTMLElement;
+      const surfaceInkClasses = (stylex.props(probe.surfaceInk).className ?? '')
+        .split(' ')
+        .filter(cls => !cls.includes('__'));
+      expect(surfaceInkClasses.length).toBeGreaterThan(0);
+      for (const cls of surfaceInkClasses) {
+        expect(iconWrapper.className).not.toContain(cls);
+      }
+    });
+
+    it('renders no glyph for custom augmented variants (documented: they must bring their own non-colour mark)', () => {
+      const dot = renderDot({variant: 'away' as AvatarStatusDotVariant});
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+  });
+
+  describe('glyph and icon interplay', () => {
+    it('suppresses the glyph when a user icon renders: the icon is the non-colour mark', () => {
+      const dot = renderDot(
+        {variant: 'error', icon: <svg data-testid="user-icon" />},
+        48,
+      );
+      expect(screen.getByTestId('user-icon')).toBeInTheDocument();
+      expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+    });
+
+    it('keeps the glyph at the smallest tier where icons never render', () => {
+      const dot = renderDot(
+        {variant: 'error', icon: <svg data-testid="user-icon" />},
+        36,
+      );
+      expect(screen.queryByTestId('user-icon')).not.toBeInTheDocument();
+      expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+    });
+
+    it('keeps the glyph for non-renderable icons: booleans from `cond && <Icon />` render nothing', () => {
+      for (const nonRenderable of [true, false, ''] as const) {
+        const dot = renderDot({variant: 'error', icon: nonRenderable}, 48);
+        expect(
+          dot.querySelector(GLYPH_SELECTOR),
+          `icon={${JSON.stringify(nonRenderable)}}`,
+        ).not.toBeNull();
+      }
+    });
+  });
+
+  describe('existing contract', () => {
+    it('exposes role="img" with the label as accessible name when label is provided', () => {
+      const dot = renderDot({variant: 'success', label: 'Online'});
+      expect(dot).toHaveAttribute('role', 'img');
+      expect(dot).toHaveAttribute('aria-label', 'Online');
+    });
+
+    it('has no img role without a label', () => {
+      const dot = renderDot({variant: 'success'});
+      expect(dot).not.toHaveAttribute('role');
+    });
+
+    it('reflects the variant as a data attribute for theming', () => {
+      const dot = renderDot({variant: 'neutral'});
+      expect(dot).toHaveAttribute('data-variant', 'neutral');
+    });
+
+    it('renders the user icon at tiers with room for it, hidden from assistive tech', () => {
+      renderDot(
+        {variant: 'success', icon: <svg data-testid="user-icon" />},
+        128,
+      );
+      const icon = screen.getByTestId('user-icon');
+      expect(icon).toBeInTheDocument();
+      expect(icon.parentElement).toHaveAttribute('aria-hidden', 'true');
+    });
+  });
+});

package/src/Avatar/AvatarStatusDot.tsx

@@ -20,37 +20,49 @@ import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 /**
- * Resolves the status dot size, border width, and icon size based on the
- * avatar size.
+ * Discrete size tier of the status dot, derived from the avatar size.
+ * Keys the built-in shape glyph's stroke weight — see `GLYPH_STROKE_WIDTH`.
+ */
+type StatusDotSizeTier = 'small' | 'medium' | 'large';
+
+/**
+ * Resolves the status dot size, border width, icon size, and size tier
+ * 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       | 10px | 1px    | —    |
- *   | 40–72px      | 20px | 2px    | 12px |
- *   | ≥ 96px       | 32px | 4px    | 18px |
+ *   | Avatar size  | Tier   | Dot  | Border | Icon | Field | Glyph stroke |
+ *   |--------------|--------|------|--------|------|-------|--------------|
+ *   | ≤ 36px       | small  | 10px | 1px    | —    | 8px   | 1px          |
+ *   | 40–72px      | medium | 20px | 2px    | 12px | 16px  | 1.5px        |
+ *   | ≥ 96px       | large  | 32px | 4px    | 18px | 24px  | 2px          |
+ *
+ * "Field" is the dot's inner field — the dot minus both borders — that the
+ * shape glyph is drawn into; see `GLYPH_STROKE_WIDTH` for the stroke ladder.
  *
  * Icons are not rendered at the smallest tier — there isn't enough
- * room for them to be legible.
+ * room for them to be legible. The built-in shape glyphs (see
+ * `glyphShapeMap`) do render there, so status stays distinguishable
+ * without colour at every size.
  */
 function resolveStatusDotSize(avatarSize: number): {
   dotSize: number;
   borderWidth: number;
   iconSize: number;
+  tier: StatusDotSizeTier;
 } {
   if (avatarSize <= 36) {
-    return {dotSize: 10, borderWidth: 1, iconSize: 0};
+    return {dotSize: 10, borderWidth: 1, iconSize: 0, tier: 'small'};
   }
   if (avatarSize <= 72) {
-    return {dotSize: 20, borderWidth: 2, iconSize: 12};
+    return {dotSize: 20, borderWidth: 2, iconSize: 12, tier: 'medium'};
   }
-  return {dotSize: 32, borderWidth: 4, iconSize: 18};
+  return {dotSize: 32, borderWidth: 4, iconSize: 18, tier: 'large'};
 }
 
 /**
@@ -65,6 +77,13 @@ function resolveStatusDotSize(avatarSize: number): {
  *   }
  * }
  * ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
  */
 export interface AvatarStatusDotVariantMap {
   success: true;
@@ -80,12 +99,14 @@ export type AvatarStatusDotVariant = keyof AvatarStatusDotVariantMap;
 export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
-   * The semantic color variant of the dot.
-   * - `success` — green dot (e.g. online, accepted)
-   * - `neutral` — gray dot (e.g. offline, pending)
-   * - `error` — red dot (e.g. busy, rejected)
+   * The semantic variant of the dot. Each variant pairs a colour with a
+   * distinct built-in shape so status is never conveyed by colour alone
+   * (WCAG 2.1 SC 1.4.1):
+   * - `success` — filled green dot (e.g. online, accepted)
+   * - `neutral` — grey ring (e.g. away, offline, pending)
+   * - `error` — red dot with a minus bar (e.g. busy, do not disturb)
    *
-   * Matches the `variant` convention from `StatusDot`.
+   * Matches the `variant` naming convention from `StatusDot`.
    * @default 'success'
    */
   variant?: AvatarStatusDotVariant;
@@ -93,6 +114,13 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
    * Accessible label for the status dot.
    * Describes the meaning of the indicator for screen readers
    * (e.g. "Online", "Accepted", "John Doe is busy").
+   *
+   * Note: inside an Avatar the dot sits in the avatar's `role="img"`
+   * subtree, where descendant semantics are pruned — the dot is never its
+   * own stop there. Instead, Avatar reads this `label` and composes it into
+   * its own accessible name (e.g. "Jane Doe, Online"), which is how the
+   * status reaches assistive tech (WCAG 4.1.2). Standalone dots (outside an
+   * Avatar) expose `role="img"` with this label directly.
    */
   label?: string;
   /**
@@ -101,6 +129,14 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
    * The icon is automatically sized to fit the dot and hidden
    * at the smallest avatar sizes where there isn't enough room.
    *
+   * A rendered icon replaces the variant's built-in shape glyph, so use a
+   * different icon per status — the same icon on every variant leaves the
+   * statuses distinguishable by colour alone (WCAG 1.4.1). At the smallest
+   * avatar sizes the built-in glyph still shows instead of the icon.
+   * Booleans and empty strings are ignored (safe for `cond && <Icon />`),
+   * but a component that renders nothing still counts as an icon and
+   * suppresses the glyph.
+   *
    * @example
    * ```
    * <AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />
@@ -119,20 +155,29 @@ const styles = stylex.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
+  // Each variant sets both the plate colour and the ink colour. Everything
+  // drawn on the dot — the shape glyph and any user `icon` — paints from
+  // `currentColor`, so the two can never drift out of contrast.
   success: {
     backgroundColor: colorVars['--color-success'],
+    color: colorVars['--color-background-surface'],
   },
+  // The ring variant inverts: a hollow shape only reads as hollow if its
+  // interior is not the variant colour, so the plate is surface and the
+  // colour moves to the stroke. This also keeps a user `icon` legible on
+  // it — surface ink on a surface plate would be invisible.
   neutral: {
-    backgroundColor: colorVars['--color-text-secondary'],
+    backgroundColor: colorVars['--color-background-surface'],
+    color: colorVars['--color-text-secondary'],
   },
   error: {
     backgroundColor: colorVars['--color-error'],
+    color: colorVars['--color-background-surface'],
   },
   icon: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    color: colorVars['--color-background-surface'],
     lineHeight: 0,
   },
 });
@@ -157,10 +202,112 @@ const variantStyleMap: Partial<
   error: styles.error,
 };
 
+/**
+ * Built-in shape glyph per variant, so each status differs by shape and not
+ * only by colour (WCAG 2.1 SC 1.4.1). The glyph is a stroked inline SVG
+ * painted in `currentColor`:
+ * - `ring` — a stroked circle on a surface plate; the dot reads as hollow
+ *   (away/offline).
+ * - `minus` — a round-capped bar across the filled dot; the dot reads as
+ *   "do not disturb" (busy).
+ *
+ * `success` stays the plain filled dot — filled, hollow, and barred are the
+ * three distinct fill topologies. Custom augmented variants have no entry
+ * and render no glyph; see the `AvatarStatusDotVariantMap` docs.
+ */
+type AvatarStatusDotGlyphShape = 'ring' | 'minus';
+
+const glyphShapeMap: Partial<
+  Record<AvatarStatusDotVariant, AvatarStatusDotGlyphShape>
+> = {
+  neutral: 'ring',
+  error: 'minus',
+};
+
+/**
+ * Glyph stroke weight per tier, in px of the dot's inner field.
+ *
+ * Roughly `field / 12`, floored at 1px so the smallest tier stays visible.
+ * That lands on the 1 / 1.5 / 2 ladder the rest of the system draws with —
+ * `Icon`'s default set strokes at 1.5 in a 24 viewBox, as does the
+ * `CheckboxInput` checkmark — rather than the 25% band a CSS box cutout
+ * produced, which was several times heavier than any other glyph we ship.
+ */
+const GLYPH_STROKE_WIDTH: Record<StatusDotSizeTier, number> = {
+  small: 1,
+  medium: 1.5,
+  large: 2,
+};
+
+/** Fraction of the inner field the minus bar spans, cap to cap. */
+const MINUS_BAR_SPAN = 0.75;
+
+/**
+ * The built-in shape glyph, drawn as a stroked inline SVG in `currentColor`.
+ *
+ * Stroking (rather than a CSS box) is what buys sub-pixel control and round
+ * line caps, so the mark stays intentional at every tier — including the
+ * 10px dot, where a box cutout can only land on whole pixels.
+ *
+ * `viewBox` is one user unit per px of the inner field, so every value here
+ * is literal px.
+ */
+function StatusDotGlyph({
+  shape,
+  field,
+  stroke,
+}: {
+  shape: AvatarStatusDotGlyphShape;
+  field: number;
+  stroke: number;
+}) {
+  const center = field / 2;
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox={`0 0 ${field} ${field}`}
+      width={field}
+      height={field}
+      fill="none"
+      {...themeProps('avatar-status-dot-glyph', {shape})}>
+      {shape === 'ring' ? (
+        // Radius is to the stroke centreline, so the ring's outer edge lands
+        // exactly on the inner field and never clips against the border.
+        <circle
+          cx={center}
+          cy={center}
+          r={(field - stroke) / 2}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={stroke}
+        />
+      ) : (
+        // Ends inset by half the stroke so the round caps land inside the
+        // span rather than overhanging it.
+        <line
+          x1={(field * (1 - MINUS_BAR_SPAN)) / 2 + stroke / 2}
+          y1={center}
+          x2={(field * (1 + MINUS_BAR_SPAN)) / 2 - stroke / 2}
+          y2={center}
+          stroke="currentColor"
+          strokeWidth={stroke}
+          strokeLinecap="round"
+        />
+      )}
+    </svg>
+  );
+}
+
 /**
  * A status indicator dot that automatically scales to match the parent
  * Avatar's size.
  *
+ * Each variant pairs a colour with a distinct built-in shape (filled dot,
+ * ring, minus bar) so status stays distinguishable without colour
+ * perception (WCAG 2.1 SC 1.4.1). Themes can target the shape glyph via
+ * the `astryx-avatar-status-dot-glyph` class and its `data-shape`
+ * attribute.
+ *
  * Must be used inside an Avatar's `status` prop so it can read
  * the avatar size from context.
  *
@@ -189,7 +336,12 @@ export function AvatarStatusDot({
   ...props
 }: AvatarStatusDotProps) {
   const avatarSize = use(AvatarSizeContext);
-  const {dotSize, borderWidth, iconSize} = resolveStatusDotSize(avatarSize);
+  const {dotSize, borderWidth, iconSize, tier} =
+    resolveStatusDotSize(avatarSize);
+  const showsIcon = isRenderable(icon) && iconSize > 0;
+  // A rendered icon is itself a non-colour mark; overlaying both cutouts in
+  // the dot's small inner field would make each illegible.
+  const glyphShape = showsIcon ? undefined : glyphShapeMap[variant];
 
   return (
     <div
@@ -207,13 +359,20 @@ export function AvatarStatusDot({
         className,
         style,
       )}>
-      {icon && iconSize > 0 && (
+      {showsIcon && (
         <span
           aria-hidden="true"
           {...stylex.props(styles.icon, dynamicStyles.iconSize(iconSize))}>
           {icon}
         </span>
       )}
+      {glyphShape && (
+        <StatusDotGlyph
+          shape={glyphShape}
+          field={dotSize - borderWidth * 2}
+          stroke={GLYPH_STROKE_WIDTH[tier]}
+        />
+      )}
     </div>
   );
 }

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -14,6 +14,7 @@ export const docs = {
       {guidance: true, description: 'Set max to limit visible avatars when the list is long; 3-5 is typical.'},
       {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: false, description: "Don't nest AvatarGroups; use a single group with all avatars."},
     ],
     anatomy: [
@@ -94,6 +95,7 @@ export const docsDense = {
       {guidance: true, description: 'Set max to limit visible avatars (3-5 typical).'},
       {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: false, description: "Don't nest AvatarGroups."},
     ],
   },