@astryxdesign/core 0.1.8 → 0.1.9

package/src/Chat/ChatContext.tsx

@@ -5,11 +5,14 @@
 /**
  * @file ChatContext.tsx
  * @input Uses React createContext
- * @output Exports ChatMessageContext for sharing sender/density between Chat components
- * @position Internal context; consumed by ChatMessage and ChatMessageBubble
+ * @output Exports Chat message/list/composer/layout contexts. The composer
+ *   context (value + input-control registration) is public composition API,
+ *   re-exported from Chat/index.ts for custom inputs.
+ * @position Shared contexts; consumed by ChatMessage, ChatComposer,
+ *   ChatComposerInput, ChatSendButton, and custom inputs.
  */
 
-import {createContext, use} from 'react';
+import {createContext, use, type RefObject} from 'react';
 
 export type ChatMessageSender = 'user' | 'assistant' | 'system';
 export type ChatDensity = 'compact' | 'balanced' | 'spacious';
@@ -19,8 +22,9 @@ export interface ChatMessageContextValue {
   density: ChatDensity;
 }
 
-export const ChatMessageContext =
-  createContext<ChatMessageContextValue | null>(null);
+export const ChatMessageContext = createContext<ChatMessageContextValue | null>(
+  null,
+);
 ChatMessageContext.displayName = 'ChatMessageContext';
 
 export function useChatMessageContext(): ChatMessageContextValue | null {
@@ -31,9 +35,7 @@ export interface ChatListContextValue {
   density: ChatDensity;
 }
 
-export const ChatListContext = createContext<ChatListContextValue | null>(
-  null,
-);
+export const ChatListContext = createContext<ChatListContextValue | null>(null);
 ChatListContext.displayName = 'ChatListContext';
 
 export function useChatListContext(): ChatListContextValue | null {
@@ -44,6 +46,21 @@ export function useChatListContext(): ChatListContextValue | null {
 // Composer context — shared state between ChatComposer and ChatComposerInput
 // =============================================================================
 
+/**
+ * Imperative surface the composer shell can invoke on its input slot.
+ *
+ * The input is one slot inside the composer body — it does not span the whole
+ * body — so shell-level interactions like "click empty space to focus the
+ * input" must flow shell → input. A custom input registers this control (via
+ * `ChatComposerContextValue.inputControlRef`) so the shell can drive it
+ * without knowing its DOM shape. Optional methods can be added over time;
+ * inputs implement only what they support.
+ */
+export interface ChatComposerInputControl {
+  /** Move keyboard focus into the input. */
+  focus: () => void;
+}
+
 export interface ChatComposerContextValue {
   value: string;
   onChange: (value: string) => void;
@@ -53,6 +70,15 @@ export interface ChatComposerContextValue {
   isStopShown: boolean;
   canSend: boolean;
   onStop?: () => void;
+  /**
+   * Mutable handle the input slot populates with its {@link
+   * ChatComposerInputControl}. The shell reads `.current` to drive the input
+   * (e.g. focus on body click). A custom input assigns
+   * `inputControlRef.current = { focus }` on mount and clears it on unmount.
+   * When unset, the shell falls back to focusing a `contenteditable`/`textarea`
+   * it finds in the body.
+   */
+  inputControlRef?: RefObject<ChatComposerInputControl | null>;
 }
 
 export const ChatComposerContext =
@@ -74,8 +100,9 @@ export interface ChatLayoutContextValue {
   contentRef: (el: HTMLElement | null) => void;
 }
 
-export const ChatLayoutContext =
-  createContext<ChatLayoutContextValue | null>(null);
+export const ChatLayoutContext = createContext<ChatLayoutContextValue | null>(
+  null,
+);
 ChatLayoutContext.displayName = 'ChatLayoutContext';
 
 export function useChatLayoutContext(): ChatLayoutContextValue | null {

package/src/Chat/ChatDictationButton.tsx

@@ -66,7 +66,10 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-full'],
     transformOrigin: 'center',
     transitionProperty: 'transform, background-color',
-    transitionDuration: '0.06s',
+    transitionDuration: {
+      default: '0.06s',
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
     transitionTimingFunction: 'ease-out',
   },
 });

package/src/Chat/ChatLayout.tsx

@@ -276,7 +276,9 @@ export function ChatLayout({
   const defaultScrollButton = (
     <ChatLayoutScrollButton
       isVisible={scroll.isScrolledUp || newMsgs.hasNewMessages}
-      label={newMsgs.hasNewMessages ? t('@astryx.chatLayout.newMessages') : undefined}
+      label={
+        newMsgs.hasNewMessages ? t('@astryx.chatLayout.newMessages') : undefined
+      }
       onClick={() => {
         newMsgs.dismiss();
         scroll.scrollToBottom();

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -69,7 +69,10 @@ const styles = stylex.create({
     height: '32px',
     transitionProperty: 'opacity, transform, max-width',
     transitionTimingFunction: easeVars['--ease-standard'],
-    transitionDuration: durationVars['--duration-fast-max'],
+    transitionDuration: {
+      default: durationVars['--duration-fast-max'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
   },
   hidden: {
     opacity: 0,
@@ -135,7 +138,9 @@ export function ChatLayoutScrollButton({
         )}>
         <Button
           label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}
-          aria-label={label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')}
+          aria-label={
+            label ?? t('@astryx.chatLayoutScrollButton.scrollToBottom')
+          }
           icon={<Icon icon="chevronDown" size="md" />}
           variant="ghost"
           size="md"

package/src/Chat/ChatMessageMetadata.tsx

@@ -122,8 +122,7 @@ export function ChatMessageMetadata({
   const sender = msgContext?.sender ?? 'assistant';
 
   const statusConfig = status != null ? STATUS_CONFIG[status] : null;
-  const statusLabel =
-    statusConfig != null ? t(statusConfig.i18nKey) : '';
+  const statusLabel = statusConfig != null ? t(statusConfig.i18nKey) : '';
 
   const hasContent =
     timestamp != null || footer != null || statusConfig != null;

package/src/Chat/ChatSendButton.tsx

@@ -88,7 +88,10 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
     stopIcon,
     size = 'md',
     xstyle,
+    className,
+    style,
     ref,
+    ...rest
   } = props;
 
   const handleSend = onSend ?? (() => context?.onSubmit(''));
@@ -96,7 +99,11 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
   return (
     <Button
       ref={ref}
-      label={isStopShown ? t('@astryx.chatSendButton.stop') : t('@astryx.chatSendButton.send')}
+      label={
+        isStopShown
+          ? t('@astryx.chatSendButton.stop')
+          : t('@astryx.chatSendButton.send')
+      }
       variant={isStopShown ? 'secondary' : 'primary'}
       size={size}
       icon={
@@ -107,7 +114,10 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
       isIconOnly
       isDisabled={!isStopShown && isDisabled}
       onClick={isStopShown ? onStop : handleSend}
+      {...rest}
       {...themeProps('chat-send-button')}
+      className={className}
+      style={style}
       xstyle={[styles.root, xstyle]}
     />
   );

package/src/Chat/ChatToolCalls.test.tsx

@@ -133,6 +133,70 @@ describe('ChatToolCalls', () => {
     expect(panel).toHaveTextContent('file contents here');
   });
 
+  it('exposes the error message as text without requiring hover', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+          },
+        ]}
+      />,
+    );
+    // The message must exist as real (screen-reader-visible) text content,
+    // not only inside a hover-only title attribute.
+    expect(screen.getByText(/Command exited with code 1/)).toBeInTheDocument();
+  });
+
+  it('includes the error message in the accessible name of an expandable error row', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+            resultDetail: <div>stderr output</div>,
+          },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole('button', {name: /Command exited with code 1/}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps the hover tooltip on the error status icon', () => {
+    const {container} = render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'bash',
+            status: 'error',
+            errorMessage: 'Command exited with code 1',
+          },
+        ]}
+      />,
+    );
+    expect(
+      container.querySelector('[title="Command exited with code 1"]'),
+    ).not.toBeNull();
+  });
+
+  it('renders no error text for non-error calls', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {name: 'bash', status: 'complete', errorMessage: 'stale message'},
+        ]}
+      />,
+    );
+    expect(screen.queryByText(/stale message/)).not.toBeInTheDocument();
+    expect(screen.queryByText(/Error:/)).not.toBeInTheDocument();
+  });
+
   it('points the group header aria-controls at the content region', () => {
     render(
       <ChatToolCalls

package/src/Chat/ChatToolCalls.tsx

@@ -35,6 +35,7 @@ import {getKey, mergeProps} from '../utils';
 import {Badge} from '../Badge';
 import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -60,7 +61,11 @@ export interface ChatToolCallItem {
   deletions?: number;
   /** Additional info rendered after the label. Free-form ReactNode. */
   stats?: ReactNode;
-  /** Error message when status is 'error'. Shown in a tooltip on the status icon. */
+  /**
+   * Error message when status is 'error'. Rendered as visually hidden text in
+   * the row (so screen readers and keyboard users perceive it) and echoed in a
+   * hover tooltip on the status icon.
+   */
   errorMessage?: string;
   /** Unique key for React list rendering. Derived from stable metadata if omitted. */
   key?: string;
@@ -128,7 +133,10 @@ const styles = stylex.create({
     width: '14px',
     height: '14px',
     color: colorVars['--color-text-disabled'],
-    transition: `transform ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+    transition: {
+      default: `transform ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
   },
   chevronExpanded: {
     transform: 'rotate(180deg)',
@@ -136,7 +144,10 @@ const styles = stylex.create({
   groupContent: {
     display: 'grid',
     gridTemplateRows: '0fr',
-    transition: `grid-template-rows ${durationVars['--duration-medium']} ${easeVars['--ease-standard']}`,
+    transition: {
+      default: `grid-template-rows ${durationVars['--duration-medium']} ${easeVars['--ease-standard']}`,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
   },
   groupContentExpanded: {
     gridTemplateRows: '1fr',
@@ -261,7 +272,10 @@ const styles = stylex.create({
     width: '14px',
     height: '14px',
     color: colorVars['--color-text-disabled'],
-    transition: `transform ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+    transition: {
+      default: `transform ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     marginInlineStart: 'auto',
   },
   callDetailContent: {
@@ -395,6 +409,13 @@ function CallRow({call}: {call: ChatToolCallItem}) {
             </span>
           </>
         )}
+        {status === 'error' && call.errorMessage != null && (
+          // The title attribute above is hover-only; expose the error detail
+          // as real text so it reaches screen readers, keyboard, and touch
+          // users. Rendering it inside the row also folds it into the
+          // accessible name of expandable (role="button") rows.
+          <VisuallyHidden>{`Error: ${call.errorMessage}`}</VisuallyHidden>
+        )}
       </span>
       <span {...stylex.props(styles.callName)}>{call.name}</span>
       {call.node != null && (

package/src/Chat/index.ts

@@ -81,7 +81,11 @@ export type {
   TokenPortal,
 } from './useChatComposerTokens';
 export type {ChatMessageSender, ChatDensity} from './ChatContext';
-export {useChatLayoutContext} from './ChatContext';
+export {useChatLayoutContext, useChatComposerContext} from './ChatContext';
+export type {
+  ChatComposerContextValue,
+  ChatComposerInputControl,
+} from './ChatContext';
 
 export {ChatToolCalls} from './ChatToolCalls';
 export type {

package/src/Chat/useChatStreamScroll.test.tsx

@@ -45,6 +45,23 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
+// The global test setup polyfills matchMedia with a never-matching stub;
+// this override makes only the reduced-motion query match, mirroring the
+// pattern in useStreamingText.test.ts. Undone by afterEach's
+// unstubAllGlobals.
+function stubReducedMotion() {
+  vi.stubGlobal('matchMedia', (query: string) => ({
+    matches: query.includes('prefers-reduced-motion'),
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }));
+}
+
 function setGeometry(
   el: HTMLElement,
   {scrollHeight, clientHeight}: {scrollHeight: number; clientHeight: number},
@@ -166,3 +183,35 @@ describe("useChatStreamScroll — scrollToBottom({behavior: 'instant'})", () =>
     expect(rafQueue.length).toBeGreaterThan(0);
   });
 });
+
+describe('useChatStreamScroll — prefers-reduced-motion', () => {
+  it('streaming growth jumps synchronously instead of springing', () => {
+    stubReducedMotion();
+    const {api, el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf(); // consume the mount jump
+    expect(el.scrollTop).toBe(600);
+
+    // Post-first-fill growth would normally take the spring path; under
+    // reduced motion it must land in the same synchronous step.
+    setGeometry(el, {scrollHeight: 1400, clientHeight: 400});
+    rafQueue = [];
+    act(() => api.current!.scrollIfLocked());
+    expect(el.scrollTop).toBe(1000);
+    expect(rafQueue).toHaveLength(0);
+  });
+
+  it('default scrollToBottom falls back to an instant jump', () => {
+    stubReducedMotion();
+    const {api, el} = renderHook();
+    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
+    flushRaf();
+    el.scrollTop = 100; // user scrolled up
+
+    rafQueue = [];
+    act(() => api.current!.scrollToBottom());
+    expect(el.scrollTop).toBe(600);
+    expect(rafQueue).toHaveLength(0);
+    expect(api.current!.isLocked).toBe(true);
+  });
+});

package/src/Chat/useChatStreamScroll.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useChatStreamScroll.ts
- * @input Uses React refs, state, callbacks
+ * @input Uses React refs, state, callbacks, useMediaQuery
  * @output Exports useChatStreamScroll hook for AI chat scroll behavior
  * @position Utility hook — used by ChatLayout, also usable standalone
  *
@@ -15,6 +15,8 @@
  * - The first fill positions instantly (whether content is present at
  *   mount or arrives async); only subsequent growth springs
  * - `scrollToBottom({behavior: 'instant'})` jumps in one frame, no animation
+ * - Under `prefers-reduced-motion`, every spring path falls back to the
+ *   same instant jump — following still works, it just doesn't animate
  *
  * Uses scroll direction (lastScrollTop comparison) to detect user
  * intent — works for wheel, touch, scrollbar drag, keyboard, everything.
@@ -26,6 +28,7 @@
  */
 
 import {useCallback, useEffect, useRef, useState} from 'react';
+import {useMediaQuery} from '../hooks/useMediaQuery';
 
 // =============================================================================
 // Types
@@ -37,7 +40,8 @@ export interface ChatScrollToBottomOptions {
    * the spring animation. Use for programmatic positioning (opening a
    * conversation, restoring a session) — keep the default `'spring'` for
    * user-initiated scrolls like the scroll-to-bottom button. Mirrors the
-   * DOM's `scrollTo({behavior})`.
+   * DOM's `scrollTo({behavior})`. When the user prefers reduced motion,
+   * `'spring'` also jumps instantly.
    * @default 'spring'
    */
   behavior?: 'instant' | 'spring';
@@ -189,14 +193,6 @@ export function useChatStreamScroll({
     requestAnimationFrame(animate);
   }, [scrollRef, damping, stiffness, mass]);
 
-  const startAnimation = useCallback(() => {
-    if (!animatingRef.current && lockedRef.current) {
-      animatingRef.current = true;
-      lastTickRef.current = undefined;
-      requestAnimationFrame(animate);
-    }
-  }, [animate]);
-
   // Jump to the bottom in a single frame — cancels any in-flight spring so
   // a later animation tick can't fight the assignment.
   const jumpToBottom = useCallback(() => {
@@ -211,6 +207,27 @@ export function useChatStreamScroll({
     lastScrollTopRef.current = el.scrollTop;
   }, [scrollRef]);
 
+  const prefersReducedMotion = useMediaQuery(
+    '(prefers-reduced-motion: reduce)',
+  );
+
+  // Every spring entry point (scrollToBottom, lock, scrollIfLocked growth
+  // follow) funnels through here, so this one branch covers them all.
+  const startAnimation = useCallback(() => {
+    if (!lockedRef.current) {
+      return;
+    }
+    if (prefersReducedMotion) {
+      jumpToBottom();
+      return;
+    }
+    if (!animatingRef.current) {
+      animatingRef.current = true;
+      lastTickRef.current = undefined;
+      requestAnimationFrame(animate);
+    }
+  }, [animate, jumpToBottom, prefersReducedMotion]);
+
   // --- Public API ---
 
   const scrollToBottom = useCallback(

package/src/Chat/useSpeechRecognition.ts

@@ -242,7 +242,7 @@ async function createVolumeAnalyser(
 
 let _sharedAudioCtx: AudioContext | null = null;
 
-export function getDefaultAudioContext(): AudioContext {
+function getDefaultAudioContext(): AudioContext {
   if (!_sharedAudioCtx || _sharedAudioCtx.state === 'closed') {
     _sharedAudioCtx = new AudioContext();
   }

package/src/Chat/useTriggerMenu.tsx

@@ -699,7 +699,9 @@ export function useTriggerMenu(
       <div
         id={listboxId}
         role="listbox"
-        aria-label={trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')}
+        aria-label={
+          trigger?.menuLabel ?? t('@astryx.chatTriggerMenu.suggestions')
+        }
         {...mergeProps(
           themeProps('trigger-menu'),
           stylex.props(styles.dropdown),

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -9,10 +9,15 @@
  * SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
@@ -333,6 +338,32 @@ describe('CheckboxInput', () => {
     );
   });
 
+  // Regression: the status is conditionally mounted, so it must be announced
+  // through the persistent useAnnounce live region — a live region born
+  // together with its content is not reliably announced.
+  it('announces a status message that appears after mount', async () => {
+    const {rerender} = render(
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+    );
+    expect(
+      document.querySelector('[data-astryx-live-region="assertive"]'),
+    ).toBeNull();
+
+    rerender(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required field'}}
+      />,
+    );
+    await waitFor(() => {
+      expect(
+        document.querySelector('[data-astryx-live-region="assertive"]'),
+      ).toHaveTextContent('Required field');
+    });
+  });
+
   describe('disabledMessage', () => {
     const h = {hidden: true} as const;
 

package/src/CheckboxInput/CheckboxInput.tsx

@@ -166,7 +166,7 @@ const styles = stylex.create({
   indeterminateMark: {
     display: 'none',
     backgroundColor: colorVars['--color-on-accent'],
-    borderRadius: 1,
+    borderRadius: radiusVars['--radius-full'],
   },
   indeterminateMarkVisible: {
     display: 'block',

package/src/CheckboxList/CheckboxList.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When CheckboxList.tsx or CheckboxListItem.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {
   render,
   screen,
@@ -20,8 +20,16 @@ import {
 import userEvent from '@testing-library/user-event';
 import {CheckboxList} from './CheckboxList';
 import {CheckboxListItem} from './CheckboxListItem';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {List} from '../List/List';
 
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
 // reflects its open state via a `popover-open` attribute the tests can assert.
 beforeEach(() => {
@@ -437,6 +445,71 @@ describe('CheckboxListItem standalone mode', () => {
   });
 });
 
+describe('CheckboxListItem accessible name', () => {
+  it('names the checkbox from a string label', () => {
+    render(
+      <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+        <CheckboxListItem label="Option A" value="a" />
+      </CheckboxList>,
+    );
+    expect(
+      screen.getByRole('checkbox', {name: 'Option A'}),
+    ).toBeInTheDocument();
+  });
+
+  it('names the checkbox from aria-label when the label is a ReactNode', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(
+      <CheckboxList label="Plans" value={[]} onChange={() => {}}>
+        <CheckboxListItem
+          label={
+            <span>
+              Pro plan <em>(recommended)</em>
+            </span>
+          }
+          aria-label="Pro plan"
+          value="pro"
+        />
+      </CheckboxList>,
+    );
+    expect(
+      screen.getByRole('checkbox', {name: 'Pro plan'}),
+    ).toBeInTheDocument();
+    // A named checkbox needs no dev guidance.
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('warns once when a ReactNode label has no aria-label', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const richLabel = (
+      <span>
+        Pro plan <em>(recommended)</em>
+      </span>
+    );
+    const {rerender} = render(
+      <CheckboxList label="Plans" value={[]} onChange={() => {}}>
+        <CheckboxListItem label={richLabel} value="pro" />
+      </CheckboxList>,
+    );
+    // Falls back to the generic name, and tells the developer how to fix it.
+    expect(
+      screen.getByRole('checkbox', {name: 'Checkbox'}),
+    ).toBeInTheDocument();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain('aria-label');
+
+    // Warn once per item instance — re-renders don't repeat it.
+    rerender(
+      <CheckboxList label="Plans" value={['pro']} onChange={() => {}}>
+        <CheckboxListItem label={richLabel} value="pro" />
+      </CheckboxList>,
+    );
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    warnSpy.mockRestore();
+  });
+});
+
 describe('CheckboxListItem ARIA props', () => {
   it('conveys checked state via the inner checkbox, not aria-checked on the listitem', () => {
     render(
@@ -567,7 +640,7 @@ describe('CheckboxListItem ARIA props', () => {
     expect(changeAction).toHaveBeenCalledWith(['a']);
   });
 
-  it('forwards arbitrary aria attributes to the list item DOM element', () => {
+  it('forwards arbitrary aria attributes to the list item, but aria-label names the checkbox', () => {
     render(
       <List>
         <CheckboxListItem
@@ -578,8 +651,13 @@ describe('CheckboxListItem ARIA props', () => {
       </List>,
     );
     const item = screen.getByRole('listitem');
+    // Arbitrary aria-* still forward to the row...
     expect(item).toHaveAttribute('aria-describedby', 'help-text');
-    expect(item).toHaveAttribute('aria-label', 'custom label');
+    // ...but aria-label names the checkbox control, not the row.
+    expect(item).not.toHaveAttribute('aria-label');
+    expect(
+      screen.getByRole('checkbox', {name: 'custom label'}),
+    ).toBeInTheDocument();
   });
 
   describe('disabledMessage', () => {