@womp/kookie-ui 0.23.0 → 0.25.0

package/src/components/accordion.css

@@ -12,13 +12,13 @@
       border-radius: var(--radius-surface-1);
     }
     &:where(.kui-r-size-2) {
-      border-radius: var(--radius-surface-1);
+      border-radius: var(--radius-surface-2);
     }
     &:where(.kui-r-size-3) {
-      border-radius: var(--radius-surface-1);
+      border-radius: var(--radius-surface-3);
     }
     &:where(.kui-r-size-4) {
-      border-radius: var(--radius-surface-1);
+      border-radius: var(--radius-surface-4);
     }
   }
 }
@@ -79,25 +79,67 @@
   cursor: pointer;
 }
 
-/* Size variants */
-:where(.kui-AccordionRoot:where(.kui-r-size-1)) .kui-AccordionTrigger {
-  padding: var(--space-3) var(--space-4);
-  font-size: var(--font-size-1);
+/* Size variants, per breakpoint */
+@breakpoints {
+  :where(.kui-AccordionRoot:where(.kui-r-size-1)) .kui-AccordionTrigger {
+    padding: var(--space-3) var(--space-4);
+    font-size: var(--font-size-1);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-2)) .kui-AccordionTrigger {
+    padding: var(--space-4) var(--space-5);
+    font-size: var(--font-size-2);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-3)) .kui-AccordionTrigger {
+    padding: var(--space-5) var(--space-6);
+    font-size: var(--font-size-3);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-4)) .kui-AccordionTrigger {
+    padding: var(--space-6) var(--space-7);
+    font-size: var(--font-size-4);
+  }
 }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-2)) .kui-AccordionTrigger {
-  padding: var(--space-4) var(--space-5);
-  font-size: var(--font-size-2);
+/* Disclosure chevron: at the far end of the trigger, turned up while the section is open */
+.kui-AccordionChevron {
+  flex-shrink: 0;
+  width: var(--icon-size-2);
+  height: var(--icon-size-2);
+  margin-inline-start: var(--space-3);
+  color: var(--neutral-a11);
 }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-3)) .kui-AccordionTrigger {
-  padding: var(--space-5) var(--space-6);
-  font-size: var(--font-size-3);
+:where(.kui-AccordionTrigger[data-state='open']) .kui-AccordionChevron {
+  rotate: 180deg;
 }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-4)) .kui-AccordionTrigger {
-  padding: var(--space-6) var(--space-7);
-  font-size: var(--font-size-4);
+/* Chevron size, per breakpoint */
+@breakpoints {
+  :where(.kui-AccordionRoot:where(.kui-r-size-1)) .kui-AccordionChevron {
+    width: var(--icon-size-1);
+    height: var(--icon-size-1);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-2)) .kui-AccordionChevron {
+    width: var(--icon-size-2);
+    height: var(--icon-size-2);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-3)) .kui-AccordionChevron {
+    width: var(--icon-size-3);
+    height: var(--icon-size-3);
+  }
+
+  :where(.kui-AccordionRoot:where(.kui-r-size-4)) .kui-AccordionChevron {
+    width: var(--icon-size-4);
+    height: var(--icon-size-4);
+  }
+}
+
+:where(.kui-AccordionTrigger[data-disabled]) .kui-AccordionChevron {
+  color: inherit;
 }
 
 /* Trigger hover states */
@@ -120,11 +162,6 @@
   }
 }
 
-:where(.kui-AccordionRoot:where(.kui-variant-raised):focus-within) {
-  outline: 2px solid var(--focus-8);
-  outline-offset: 2px;
-}
-
 @media (hover: hover) {
   :where(.kui-AccordionRoot:where(.kui-variant-soft)) :where(.kui-AccordionTrigger:hover) {
     background-color: var(--accent-4);
@@ -157,27 +194,6 @@
   outline-offset: var(--focus-outline-offset-inset);
 }
 
-/* Variant-specific focus styles */
-:where(.kui-AccordionRoot:where(.kui-variant-soft):focus-within) {
-  outline: 2px solid var(--focus-8);
-  outline-offset: 2px;
-}
-
-:where(.kui-AccordionRoot:where(.kui-variant-surface):focus-within) {
-  outline: 2px solid var(--focus-8);
-  outline-offset: 2px;
-}
-
-:where(.kui-AccordionRoot:where(.kui-variant-outline):focus-within) {
-  outline: 2px solid var(--focus-8);
-  outline-offset: 2px;
-}
-
-:where(.kui-AccordionRoot:where(.kui-variant-ghost):focus-within) {
-  outline: 2px solid var(--focus-8);
-  outline-offset: 2px;
-}
-
 /* Accordion Content */
 .kui-AccordionContent {
   overflow: hidden;
@@ -192,25 +208,27 @@
   padding: 0 var(--space-5) var(--space-4);
 }
 
-/* Size variants for content */
-:where(.kui-AccordionRoot:where(.kui-r-size-1)) .kui-AccordionContentInner {
-  padding: 0 var(--space-4) var(--space-3);
-  font-size: var(--font-size-1);
-}
+/* Size variants for content, per breakpoint */
+@breakpoints {
+  :where(.kui-AccordionRoot:where(.kui-r-size-1)) .kui-AccordionContentInner {
+    padding: 0 var(--space-4) var(--space-3);
+    font-size: var(--font-size-1);
+  }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-2)) .kui-AccordionContentInner {
-  padding: 0 var(--space-5) var(--space-4);
-  font-size: var(--font-size-2);
-}
+  :where(.kui-AccordionRoot:where(.kui-r-size-2)) .kui-AccordionContentInner {
+    padding: 0 var(--space-5) var(--space-4);
+    font-size: var(--font-size-2);
+  }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-3)) .kui-AccordionContentInner {
-  padding: 0 var(--space-6) var(--space-5);
-  font-size: var(--font-size-3);
-}
+  :where(.kui-AccordionRoot:where(.kui-r-size-3)) .kui-AccordionContentInner {
+    padding: 0 var(--space-6) var(--space-5);
+    font-size: var(--font-size-3);
+  }
 
-:where(.kui-AccordionRoot:where(.kui-r-size-4)) .kui-AccordionContentInner {
-  padding: 0 var(--space-7) var(--space-6);
-  font-size: var(--font-size-4);
+  :where(.kui-AccordionRoot:where(.kui-r-size-4)) .kui-AccordionContentInner {
+    padding: 0 var(--space-7) var(--space-6);
+    font-size: var(--font-size-4);
+  }
 }
 
 /* Content animations */

package/src/components/accordion.tsx

@@ -9,6 +9,8 @@ import {
   accordionTriggerPropDefs,
   accordionContentPropDefs,
 } from './accordion.props.js';
+import { ChevronDownIcon } from './icons.js';
+import { Slottable } from './slot.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../helpers/theme-size.js';
 
@@ -23,9 +25,13 @@ import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-p
 
 // Root component
 type AccordionRootElement = React.ElementRef<typeof AccordionPrimitive.Root>;
-interface AccordionRootProps
-  extends ComponentPropsWithout<typeof AccordionPrimitive.Root, RemovedProps>,
-    AccordionRootOwnProps {}
+// Radix's Root props are a union of single and multiple. Omit each member on its own, so
+// `defaultValue`, `value` and `collapsible` survive with the right type for each `type`.
+type AccordionRootRadixProps =
+  | Omit<AccordionPrimitive.AccordionSingleProps, 'asChild' | 'color'>
+  | Omit<AccordionPrimitive.AccordionMultipleProps, 'asChild' | 'color'>;
+
+type AccordionRootProps = AccordionRootRadixProps & AccordionRootOwnProps;
 
 const AccordionRoot = React.forwardRef<AccordionRootElement, AccordionRootProps>(
   (ownProps, forwardedRef) => {
@@ -37,36 +43,11 @@ const AccordionRoot = React.forwardRef<AccordionRootElement, AccordionRootProps>
       typeof AccordionPrimitive.Root
     >;
 
-
     // Ensure single accordions can collapse by default unless explicitly set
     if (radixProps.type === 'single' && radixProps.collapsible === undefined) {
       radixProps.collapsible = true;
     }
 
-    // Handle Home/End key navigation for multi-item accordions
-    const handleKeyDown = React.useCallback(
-      (event: React.KeyboardEvent) => {
-        if (radixProps.type === 'multiple') {
-          const items = event.currentTarget.querySelectorAll('[data-radix-accordion-item]');
-
-          if (event.key === 'Home') {
-            event.preventDefault();
-            const firstTrigger = items[0]?.querySelector(
-              '[data-radix-accordion-trigger]',
-            ) as HTMLElement;
-            firstTrigger?.focus();
-          } else if (event.key === 'End') {
-            event.preventDefault();
-            const lastTrigger = items[items.length - 1]?.querySelector(
-              '[data-radix-accordion-trigger]',
-            ) as HTMLElement;
-            lastTrigger?.focus();
-          }
-        }
-      },
-      [radixProps.type],
-    );
-
     return (
       <AccordionPrimitive.Root
         {...radixProps}
@@ -74,7 +55,6 @@ const AccordionRoot = React.forwardRef<AccordionRootElement, AccordionRootProps>
         className={classNames('kui-AccordionRoot', className)}
         data-accent-color={color}
         data-radius={radius}
-        onKeyDown={handleKeyDown}
       />
     );
   },
@@ -133,23 +113,14 @@ const AccordionTrigger = React.forwardRef<AccordionTriggerElement, AccordionTrig
   ({ children, ...props }, forwardedRef) => {
     const { className, ...triggerProps } = extractProps(props, accordionTriggerPropDefs);
 
-    // Radix UI handles focus management automatically
-    const triggerRef = React.useRef<HTMLButtonElement>(null);
-
     return (
       <AccordionPrimitive.Trigger
         {...triggerProps}
-        ref={(node) => {
-          triggerRef.current = node;
-          if (typeof forwardedRef === 'function') {
-            forwardedRef(node);
-          } else if (forwardedRef) {
-            forwardedRef.current = node;
-          }
-        }}
+        ref={forwardedRef}
         className={classNames('kui-AccordionTrigger', className)}
       >
-        {children}
+        <Slottable>{children}</Slottable>
+        <ChevronDownIcon className="kui-AccordionChevron" aria-hidden />
       </AccordionPrimitive.Trigger>
     );
   },
@@ -171,7 +142,6 @@ const AccordionContent = React.forwardRef<AccordionContentElement, AccordionCont
         {...contentProps}
         ref={forwardedRef}
         className={classNames('kui-AccordionContent', className)}
-        aria-live="polite"
       >
         <div className="kui-AccordionContentInner">{children}</div>
       </AccordionPrimitive.Content>

package/src/components/alert-dialog.tsx

@@ -9,174 +9,82 @@ import { Theme } from './theme.js';
 import { extractProps } from '../helpers/extract-props.js';
 import { useThemeSizeProps } from '../helpers/theme-size.js';
 import { requireReactElement } from '../helpers/require-react-element.js';
+import { useBodyPointerEventsCleanup } from '../hooks/use-body-pointer-events-cleanup.js';
 
 import type { AlertDialogContentOwnProps } from './alert-dialog.props.js';
-import type {
-  ComponentPropsWithout,
-  RemovedProps,
-  ComponentPropsAs,
-} from '../helpers/component-props.js';
+import type { ComponentPropsWithout, RemovedProps, ComponentPropsAs } from '../helpers/component-props.js';
 
-interface AlertDialogRootProps
-  extends React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Root> {}
-const AlertDialogRoot: React.FC<AlertDialogRootProps> = (props) => (
-  <AlertDialogPrimitive.Root {...props} />
-);
+interface AlertDialogRootProps extends React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Root> {}
+const AlertDialogRoot: React.FC<AlertDialogRootProps> = (props) => <AlertDialogPrimitive.Root {...props} />;
 AlertDialogRoot.displayName = 'AlertDialog.Root';
 
 type AlertDialogTriggerElement = React.ElementRef<typeof AlertDialogPrimitive.Trigger>;
-interface AlertDialogTriggerProps
-  extends ComponentPropsWithout<typeof AlertDialogPrimitive.Trigger, RemovedProps> {}
-const AlertDialogTrigger = React.forwardRef<AlertDialogTriggerElement, AlertDialogTriggerProps>(
-  ({ children, ...props }, forwardedRef) => (
-    <AlertDialogPrimitive.Trigger {...props} ref={forwardedRef} asChild>
-      {requireReactElement(children)}
-    </AlertDialogPrimitive.Trigger>
-  ),
-);
+interface AlertDialogTriggerProps extends ComponentPropsWithout<typeof AlertDialogPrimitive.Trigger, RemovedProps> {}
+const AlertDialogTrigger = React.forwardRef<AlertDialogTriggerElement, AlertDialogTriggerProps>(({ children, ...props }, forwardedRef) => (
+  <AlertDialogPrimitive.Trigger {...props} ref={forwardedRef} asChild>
+    {requireReactElement(children)}
+  </AlertDialogPrimitive.Trigger>
+));
 AlertDialogTrigger.displayName = 'AlertDialog.Trigger';
 
 // Split once at module scope. `extractProps` memoises on the identity of the
 // prop def objects it is handed, so rebuilding these per render would recompile
 // them on every render.
-const {
-  align: alignPropDef,
-  ...contentPropDefs
-} = alertDialogContentPropDefs;
+const { align: alignPropDef, ...contentPropDefs } = alertDialogContentPropDefs;
 const alignPropDefs = { align: alignPropDef };
 
 type AlertDialogContentElement = React.ElementRef<typeof AlertDialogPrimitive.Content>;
-interface AlertDialogContentProps
-  extends ComponentPropsWithout<typeof AlertDialogPrimitive.Content, RemovedProps>,
-    AlertDialogContentOwnProps {
+interface AlertDialogContentProps extends ComponentPropsWithout<typeof AlertDialogPrimitive.Content, RemovedProps>, AlertDialogContentOwnProps {
   container?: React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Portal>['container'];
 }
-const AlertDialogContent = React.forwardRef<AlertDialogContentElement, AlertDialogContentProps>(
-  ({ align, ...ownProps }, forwardedRef) => {
-    const props = useThemeSizeProps(ownProps, contentPropDefs.size);
-    const { className: alignClassName } = extractProps({ align }, alignPropDefs);
-
-    const {
-      className,
-      forceMount,
-      container,
-      ...contentProps
-    } = extractProps(props, contentPropDefs);
-
-    // Focus management
-    const contentRef = React.useRef<HTMLDivElement>(null);
-    const combinedRef = React.useMemo(
-      () => (node: HTMLDivElement | null) => {
-        contentRef.current = node;
-        if (typeof forwardedRef === 'function') {
-          forwardedRef(node);
-        } else if (forwardedRef) {
-          forwardedRef.current = node;
-        }
-      },
-      [forwardedRef],
-    );
-
-    // Focus trap effect
-    React.useEffect(() => {
-      // SSR safety - only run on client
-      if (typeof window === 'undefined') return;
-
-      const content = contentRef.current;
-      if (!content) return;
-
-      const focusableElements = content.querySelectorAll(
-        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
-      );
-
-      if (focusableElements.length === 0) return;
-
-      const firstElement = focusableElements[0] as HTMLElement;
-      const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
-
-      const handleKeyDown = (event: KeyboardEvent) => {
-        if (event.key === 'Tab') {
-          if (event.shiftKey) {
-            if (document.activeElement === firstElement) {
-              event.preventDefault();
-              lastElement.focus();
-            }
-          } else {
-            if (document.activeElement === lastElement) {
-              event.preventDefault();
-              firstElement.focus();
-            }
-          }
-        }
-      };
-
-      content.addEventListener('keydown', handleKeyDown);
-
-      // Focus first element when dialog opens
-      firstElement.focus();
-
-      return () => {
-        content.removeEventListener('keydown', handleKeyDown);
-      };
-    }, []);
-
-    return (
-      <AlertDialogPrimitive.Portal container={container} forceMount={forceMount}>
-        <Theme asChild>
-          <AlertDialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-AlertDialogOverlay">
-            <div className="kui-BaseDialogScroll kui-AlertDialogScroll">
-              <div
-                className={`kui-BaseDialogScrollPadding kui-AlertDialogScrollPadding ${alignClassName}`}
-              >
-                <AlertDialogPrimitive.Content
-                  {...contentProps}
-                  ref={combinedRef}
-                  className={classNames('kui-BaseDialogContent', 'kui-AlertDialogContent', className)}
-                  tabIndex={-1}
-                  role="alertdialog"
-                  aria-modal="true"
-                  aria-describedby="alert-dialog-description"
-                  onCloseAutoFocus={(event) => {
-                    // Prevent default focus behavior
-                    event.preventDefault();
-                    // Restore pointer-events to body (Radix UI fix for issue #1241)
-                    document.body.style.pointerEvents = '';
-                  }}
-                />
-                {/* ARIA live region for screen reader announcements */}
-                <div
-                  aria-live="assertive"
-                  aria-atomic="true"
-                  className="kui-sr-only"
-                  id="alert-dialog-announcement"
-                />
-              </div>
+const AlertDialogContent = React.forwardRef<AlertDialogContentElement, AlertDialogContentProps>(({ align, ...ownProps }, forwardedRef) => {
+  const props = useThemeSizeProps(ownProps, contentPropDefs.size);
+  const { className: alignClassName } = extractProps({ align }, alignPropDefs);
+
+  const { className, forceMount, container, onCloseAutoFocus, ...contentProps } = extractProps(props, contentPropDefs);
+
+  // Same stuck pointer-events fallback as Dialog and Sheet.
+  useBodyPointerEventsCleanup();
+
+  return (
+    <AlertDialogPrimitive.Portal container={container} forceMount={forceMount}>
+      <Theme asChild>
+        <AlertDialogPrimitive.Overlay className="kui-BaseDialogOverlay kui-AlertDialogOverlay">
+          <div className="kui-BaseDialogScroll kui-AlertDialogScroll">
+            <div className={`kui-BaseDialogScrollPadding kui-AlertDialogScrollPadding ${alignClassName}`}>
+              <AlertDialogPrimitive.Content
+                {...contentProps}
+                ref={forwardedRef}
+                className={classNames('kui-BaseDialogContent', 'kui-AlertDialogContent', className)}
+                aria-modal="true"
+                onCloseAutoFocus={(event) => {
+                  // Radix returns focus to the trigger unless the caller prevents it.
+                  onCloseAutoFocus?.(event);
+                  // Restore pointer-events to body (Radix UI fix for issue #1241)
+                  document.body.style.pointerEvents = '';
+                }}
+              />
             </div>
-          </AlertDialogPrimitive.Overlay>
-        </Theme>
-      </AlertDialogPrimitive.Portal>
-    );
-  },
-);
+          </div>
+        </AlertDialogPrimitive.Overlay>
+      </Theme>
+    </AlertDialogPrimitive.Portal>
+  );
+});
 AlertDialogContent.displayName = 'AlertDialog.Content';
 
 type AlertDialogTitleElement = React.ElementRef<typeof Heading>;
 type AlertDialogTitleProps = ComponentPropsWithout<typeof Heading, 'asChild'>;
-const AlertDialogTitle = React.forwardRef<AlertDialogTitleElement, AlertDialogTitleProps>(
-  (props, forwardedRef) => (
-    <AlertDialogPrimitive.Title asChild>
-      <Heading size="5" trim="start" {...props} asChild={false} ref={forwardedRef} />
-    </AlertDialogPrimitive.Title>
-  ),
-);
+const AlertDialogTitle = React.forwardRef<AlertDialogTitleElement, AlertDialogTitleProps>((props, forwardedRef) => (
+  <AlertDialogPrimitive.Title asChild>
+    <Heading size="5" trim="start" {...props} asChild={false} ref={forwardedRef} />
+  </AlertDialogPrimitive.Title>
+));
 AlertDialogTitle.displayName = 'AlertDialog.Title';
 
 type AlertDialogDescriptionElement = HTMLParagraphElement;
 type AlertDialogDescriptionProps = ComponentPropsAs<typeof Text, 'p'>;
-const AlertDialogDescription = React.forwardRef<
-  AlertDialogDescriptionElement,
-  AlertDialogDescriptionProps
->((props, forwardedRef) => (
+const AlertDialogDescription = React.forwardRef<AlertDialogDescriptionElement, AlertDialogDescriptionProps>((props, forwardedRef) => (
   <AlertDialogPrimitive.Description asChild>
     <Text as="p" size="3" {...props} asChild={false} ref={forwardedRef} />
   </AlertDialogPrimitive.Description>
@@ -184,27 +92,21 @@ const AlertDialogDescription = React.forwardRef<
 AlertDialogDescription.displayName = 'AlertDialog.Description';
 
 type AlertDialogActionElement = React.ElementRef<typeof AlertDialogPrimitive.Action>;
-interface AlertDialogActionProps
-  extends ComponentPropsWithout<typeof AlertDialogPrimitive.Action, RemovedProps> {}
-const AlertDialogAction = React.forwardRef<AlertDialogActionElement, AlertDialogActionProps>(
-  ({ children, ...props }, forwardedRef) => (
-    <AlertDialogPrimitive.Action {...props} ref={forwardedRef} asChild>
-      {requireReactElement(children)}
-    </AlertDialogPrimitive.Action>
-  ),
-);
+interface AlertDialogActionProps extends ComponentPropsWithout<typeof AlertDialogPrimitive.Action, RemovedProps> {}
+const AlertDialogAction = React.forwardRef<AlertDialogActionElement, AlertDialogActionProps>(({ children, ...props }, forwardedRef) => (
+  <AlertDialogPrimitive.Action {...props} ref={forwardedRef} asChild>
+    {requireReactElement(children)}
+  </AlertDialogPrimitive.Action>
+));
 AlertDialogAction.displayName = 'AlertDialog.Action';
 
 type AlertDialogCancelElement = React.ElementRef<typeof AlertDialogPrimitive.Cancel>;
-interface AlertDialogCancelProps
-  extends ComponentPropsWithout<typeof AlertDialogPrimitive.Cancel, RemovedProps> {}
-const AlertDialogCancel = React.forwardRef<AlertDialogCancelElement, AlertDialogCancelProps>(
-  ({ children, ...props }, forwardedRef) => (
-    <AlertDialogPrimitive.Cancel {...props} ref={forwardedRef} asChild>
-      {requireReactElement(children)}
-    </AlertDialogPrimitive.Cancel>
-  ),
-);
+interface AlertDialogCancelProps extends ComponentPropsWithout<typeof AlertDialogPrimitive.Cancel, RemovedProps> {}
+const AlertDialogCancel = React.forwardRef<AlertDialogCancelElement, AlertDialogCancelProps>(({ children, ...props }, forwardedRef) => (
+  <AlertDialogPrimitive.Cancel {...props} ref={forwardedRef} asChild>
+    {requireReactElement(children)}
+  </AlertDialogPrimitive.Cancel>
+));
 AlertDialogCancel.displayName = 'AlertDialog.Cancel';
 
 export {

package/src/components/avatar.css

@@ -455,10 +455,14 @@
 .kui-AvatarBadge {
   position: absolute;
   bottom: 0;
-  right: 0;
+  inset-inline-end: 0;
   z-index: 1;
-  /* Indicator partially leaks out of avatar corner */
+  /* Indicator partially leaks out of avatar corner, on the inline end */
   transform: translate(25%, 25%);
+
+  &:where(:dir(rtl)) {
+    transform: translate(-25%, 25%);
+  }
 }
 
 /* Status indicator - colored dot */

package/src/components/avatar.props.tsx

@@ -20,6 +20,11 @@ const avatarPropDefs = {
    * Cannot be used together with `badge`.
    */
   status: { type: 'enum', values: accentColors, default: undefined },
+  /**
+   * The words the status dot stands for, such as "Online". A screen reader reads them with the
+   * avatar. Without it the dot is hidden from screen readers.
+   */
+  statusLabel: { type: 'string', default: undefined },
   /**
    * Custom badge content. Renders at the bottom-right corner.
    * Cannot be used together with `status`.
@@ -36,6 +41,7 @@ const avatarPropDefs = {
   variant: PropDef<(typeof variants)[number]>;
   fallback: PropDef<React.ReactNode>;
   status: PropDef<(typeof accentColors)[number] | undefined>;
+  statusLabel: PropDef<string | undefined>;
   badge: PropDef<React.ReactNode>;
   fit: PropDef<(typeof objectFitValues)[number]>;
 };