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

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

@@ -125,7 +125,7 @@ const styles = stylex.create({
     outline: 'none',
     backgroundColor: 'transparent',
     border: 'none',
-    textAlign: 'left' as const,
+    textAlign: 'start' as const,
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
@@ -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.doc.mjs

@@ -121,6 +121,12 @@ export const docs = {
       description:
         'Status indicator. Displays a colored message box below the checkbox and sets aria-invalid for errors.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
   ],
   theming: {
     targets: [

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',
@@ -198,12 +198,12 @@ const wrapperSizeStyles = stylex.create({
 
 const checkboxSizeStyles = stylex.create({
   sm: {
-    width: 18,
-    height: 18,
+    width: 20,
+    height: 20,
   },
   md: {
-    width: 22,
-    height: 22,
+    width: 24,
+    height: 24,
   },
 });
 

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -88,6 +88,12 @@ export const docs = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator ({ type, message }).',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

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', () => {

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -7,14 +7,22 @@ export const docs = {
   subComponentOf: 'CheckboxList',
   displayName: 'Checkbox List Item',
   isHiddenFromOverview: true,
-  description: 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside CheckboxList) or standalone mode (inside List).',
+  description:
+    'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside CheckboxList) or standalone mode (inside List).',
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: 'Primary text label for the item.',
+      type: 'ReactNode',
+      description:
+        'Primary text label for the item. A plain string names the checkbox automatically; a rich (ReactNode) label should be paired with aria-label so screen readers get a concise name.',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        'Plain-text accessible name for the checkbox when label is a ReactNode. Applied to the checkbox control. Without it, rich-label items all announce as the generic "Checkbox" to screen readers.',
+    },
     {
       name: 'value',
       type: 'string',
@@ -69,13 +77,24 @@ export const docs = {
       description: 'Direct check handler (standalone mode only).',
     },
   ],
+  examples: [
+    {
+      label: 'Rich label with an accessible name',
+      code: `<CheckboxListItem
+  label={<span>Pro plan <Badge label="Recommended" /></span>}
+  aria-label="Pro plan"
+  value="pro"
+/>`,
+    },
+  ],
 };
 
 export const docsZh = {
   name: 'CheckboxListItem',
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
-  description: '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
+  description:
+    '单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
   props: [
     {
       name: 'label',
@@ -83,6 +102,12 @@ export const docsZh = {
       description: '选项的主要文本标签。',
       required: true,
     },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        '当 label 是 ReactNode 时，复选框的纯文本无障碍名称。缺少它时，富标签选项都会向屏幕阅读器播报为通用的 "Checkbox"。',
+    },
     {
       name: 'value',
       type: 'string',
@@ -128,9 +153,12 @@ export const docsDense = {
   name: 'CheckboxListItem',
   isHiddenFromOverview: true,
   displayName: 'Checkbox List Item',
-  description: 'Individual checkbox item w/ label, description, end content slot.',
+  description:
+    'Individual checkbox item w/ label, description, end content slot.',
   propDescriptions: {
     label: 'Primary text label for item.',
+    'aria-label':
+      'Plain-text checkbox name when label is a ReactNode. Without it, rich-label items all announce as "Checkbox".',
     value: 'Identity key (required inside CheckboxList).',
     description: 'Secondary text below label.',
     endContent: 'Content rendered after label area.',

package/src/CheckboxList/CheckboxListItem.tsx

@@ -22,6 +22,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {composeEventHandlers} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {ListItem} from '../List/ListItem';
 import {ListContext} from '../List/ListContext';
@@ -51,6 +52,25 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
    * child components control their own text behavior).
    */
   label: ReactNode;
+  /**
+   * Plain-text accessible name for the checkbox when `label` is a ReactNode.
+   *
+   * A string `label` names the checkbox automatically. A rich (ReactNode)
+   * `label` cannot, so pass a concise string equivalent via the standard
+   * `aria-label` — otherwise the checkbox falls back to the generic name
+   * "Checkbox" and every rich-label item in a list announces identically to
+   * screen readers. Applied to the checkbox control, not the row.
+   *
+   * @example
+   * ```
+   * <CheckboxListItem
+   *   label={<span>Pro plan <Badge label="Recommended" /></span>}
+   *   aria-label="Pro plan"
+   *   value="pro"
+   * />
+   * ```
+   */
+  'aria-label'?: string;
   /**
    * Identity key for collection mode (REQUIRED inside CheckboxList).
    * Throws a runtime error if missing when used inside CheckboxList.
@@ -119,6 +139,7 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
  */
 export function CheckboxListItem({
   label,
+  'aria-label': ariaLabel,
   value,
   description,
   endContent,
@@ -142,6 +163,25 @@ export function CheckboxListItem({
     );
   }
 
+  // Accessible name for the (visually hidden) checkbox label. A string
+  // `label` names it directly; a rich label needs `aria-label`.
+  const checkboxLabel =
+    ariaLabel ??
+    (typeof label === 'string'
+      ? label
+      : t('@astryx.checkboxList.item.checkbox'));
+
+  // Dev-time guardrail: a rich label without `aria-label` leaves the
+  // checkbox with the generic name "Checkbox".
+  useDevWarning(
+    'CheckboxListItem',
+    '`label` is a ReactNode, so the checkbox falls ' +
+      'back to the generic accessible name "Checkbox". Pass ' +
+      '`aria-label` with a concise string equivalent of the visible ' +
+      'label so screen readers can tell items apart.',
+    typeof label !== 'string' && ariaLabel == null,
+  );
+
   // Density from list context for checkbox sizing
   const listCtx = use(ListContext);
   const density = listCtx?.density ?? 'balanced';
@@ -226,11 +266,7 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
-          label={
-            typeof label === 'string'
-              ? label
-              : t('@astryx.checkboxList.item.checkbox')
-          }
+          label={checkboxLabel}
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}

package/src/Citation/Citation.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
         name: 'Icon',
         required: false,
         description:
-          'An optional favicon or source icon displayed before the label text. Only available in the label variant.',
+          'An optional source icon shown before the label text. Accepts a favicon/logo image URL (via source.src) or a React node such as an Astryx <Icon>. Only available in the label variant.',
       },
       {
         name: 'Label text',
@@ -71,7 +71,7 @@ export const docs = {
       name: 'source',
       type: 'CitationSource',
       description:
-        'The citation source object containing title, url, and optional icon.',
+        'The citation source object containing title, url, an optional image src, and an optional icon node.',
       required: true,
     },
     {
@@ -121,7 +121,8 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    source: 'citation source object with title, url, optional icon.',
+    source:
+      'citation source object with title, url, optional image src, and optional icon node.',
     number: 'display index for this citation.',
     variant: 'display style: label chip with source title or compact numbered badge.',
   },

package/src/Citation/Citation.test.tsx

@@ -169,4 +169,101 @@ describe('Citation', () => {
       expect(el.classList.contains(cls)).toBe(true);
     }
   });
+
+  // --- Source icon: image URL (back-compat) vs ReactNode ---------------------
+
+  it('renders a legacy string icon as a decorative image (back-compat)', () => {
+    // Existing callers pass a favicon URL to `source.icon`. A bare string must
+    // still render as <img src>, unchanged from the original behavior.
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/favicon.png');
+    // Decorative: empty alt, and the wrapper is aria-hidden.
+    expect(img).toHaveAttribute('alt', '');
+    expect(container.querySelector('[aria-hidden="true"] img')).toBe(img);
+  });
+
+  it('renders source.src as a decorative image', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).toHaveAttribute('src', 'https://example.com/logo.png');
+    expect(img).toHaveAttribute('alt', '');
+  });
+
+  it('renders a ReactNode icon as-is (not an <img>)', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    // The node renders directly; no <img> is produced for a node icon.
+    expect(container.querySelector('img')).toBeNull();
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    // Still decorative — wrapped in an aria-hidden container.
+    expect(
+      container.querySelector(
+        '[aria-hidden="true"] [data-testid="custom-icon"]',
+      ),
+    ).not.toBeNull();
+  });
+
+  it('prefers a node icon over src when both are provided', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    expect(container.querySelector('img')).toBeNull();
+  });
+
+  it('keeps aria-label as the sole accessible name when an icon is present', () => {
+    render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={2}
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el).toHaveAttribute('aria-label', 'Citation 2: GitHub');
+  });
 });