@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Carousel/Carousel.tsx

@@ -41,8 +41,9 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {useLayer} from '../Layer';
 import {useScrollOverflow} from '../hooks/useScrollOverflow';
+import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -166,10 +167,16 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   buttonPillStart: {
-    transform: 'translateX(-50%)',
+    transform: {
+      default: 'translateX(-50%)',
+      ':is([dir="rtl"] *)': 'translateX(50%)',
+    },
   },
   buttonPillEnd: {
-    transform: 'translateX(50%)',
+    transform: {
+      default: 'translateX(50%)',
+      ':is([dir="rtl"] *)': 'translateX(-50%)',
+    },
   },
   buttonHidden: {
     opacity: 0,
@@ -347,7 +354,11 @@ export function Carousel({
       typeof window.matchMedia === 'function' &&
       window.matchMedia('(prefers-reduced-motion: reduce)').matches;
     el.scrollBy({
-      left: direction * Math.max(amount, itemWidth),
+      // `direction` is the logical intent (-1 = toward content start, +1 =
+      // toward content end). Under RTL the scroll axis is inverted (start is
+      // scrollLeft 0, the end is negative), so flip the physical delta sign.
+      left:
+        (isRtlElement(el) ? -1 : 1) * direction * Math.max(amount, itemWidth),
       behavior: prefersReducedMotion ? 'auto' : 'smooth',
     });
   }, []);
@@ -425,7 +436,11 @@ export function Carousel({
                 !overflowStart && styles.buttonHidden,
               )}>
               <Button
-                icon={<Icon icon="chevronLeft" size="xsm" />}
+                icon={
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <Icon icon="chevronLeft" size="xsm" />
+                  </span>
+                }
                 label={t('@astryx.carousel.scrollLeft')}
                 variant="ghost"
                 size="sm"
@@ -446,7 +461,11 @@ export function Carousel({
                 !overflowEnd && styles.buttonHidden,
               )}>
               <Button
-                icon={<Icon icon="chevronRight" size="xsm" />}
+                icon={
+                  <span {...stylex.props(rtlStyles.mirror)}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
+                }
                 label={t('@astryx.carousel.scrollRight')}
                 variant="ghost"
                 size="sm"

package/src/Chat/ChatComposer.doc.mjs

@@ -60,7 +60,7 @@ export const docs = {
       name: 'elevation',
       type: "'none' | 'low'",
       description:
-        "Resting elevation of the composer body. `low` (the default) keeps today's raised look — low at rest, bumping to med on hover / focus. `none` flattens it and draws a border with the same rest / hover / focus treatment as a text input (emphasized border → accent on focus, matching inset rings).",
+        "Resting elevation of the composer body. `low` (the default) keeps today's raised look: low at rest, bumping to med on hover / focus. `none` flattens it and draws a border with the same rest / hover / focus treatment as a text input (emphasized border → accent on focus, matching inset rings).",
       default: "'low'",
     },
     {
@@ -109,7 +109,7 @@ export const docs = {
     {
       name: 'input',
       type: 'ReactNode',
-      description: 'Slot: custom input element. Replaces the default input. Use ChatComposerInput for trigger menus/tokens, or wire any input (plain textarea, rich editor) to the composition contract via useChatComposerContext() — read value/onChange/onSubmit/canSend and register a focus control on inputControlRef so body-click-to-focus works.',
+      description: 'Slot: custom input element. Replaces the default input. Use ChatComposerInput for trigger menus/tokens, or wire any input (plain textarea, rich editor) to the composition contract via useChatComposerContext(): read value/onChange/onSubmit/canSend and register a focus control on inputControlRef so body-click-to-focus works.',
       slotElements: [
         {
           __element: 'TextInput',

package/src/Chat/ChatComposerInput.doc.mjs

@@ -83,7 +83,7 @@ export const docs = {
     {
       name: 'onKeyDown',
       type: '(event) => void',
-      description: 'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected — Enter never submits mid-composition.',
+      description: 'Key-down handler invoked before the built-in Enter/history behavior (after any open trigger menu). The seam for platform-specific keys: call event.preventDefault() to suppress the default submit (e.g. newline on a touch keyboard), or act on the event yourself to add behavior (e.g. submit on Cmd/Ctrl+Enter). IME composition is always respected; Enter never submits mid-composition.',
     },
   ],
 };

package/src/Chat/ChatComposerInput.tsx

@@ -238,8 +238,8 @@ const styles = stylex.create({
   placeholder: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     pointerEvents: 'none',
     color: colorVars['--color-text-secondary'],
     fontSize: {

package/src/Chat/ChatDictationButton.tsx

@@ -26,6 +26,7 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -110,13 +111,18 @@ export function ChatDictationButton({
   style,
   ...rest
 }: ChatDictationButtonProps) {
+  const t = useTranslator();
+
   if (isHiddenWhenUnsupported && !dictation.isSupported) {
     return null;
   }
 
   const {isListening, bands, volume: rawVolume} = dictation;
   const accessibleLabel =
-    label ?? (isListening ? 'Stop dictation' : 'Start dictation');
+    label ??
+    (isListening
+      ? t('@astryx.chatDictationButton.stopDictation')
+      : t('@astryx.chatDictationButton.startDictation'));
 
   // Boost each band for visibility — quiet speech (0-10%) maps to full visual range
   const boostedBands = bands.map(b => Math.min(Math.pow(b / 0.2, 0.5), 1));

package/src/Chat/ChatLayout.tsx

@@ -134,8 +134,8 @@ const styles = stylex.create({
   // --- Dock container ---
   dockContainer: {
     bottom: 0,
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     zIndex: 0,
     isolation: 'isolate',
     pointerEvents: 'none',
@@ -150,8 +150,8 @@ const styles = stylex.create({
   blurLayer: {
     position: 'absolute',
     bottom: 0,
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     pointerEvents: 'none',
     backdropFilter: 'blur(12px)',
     WebkitBackdropFilter: 'blur(12px)',

package/src/Chat/ChatMessageBubble.tsx

@@ -160,27 +160,32 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     color: colorVars['--color-text-primary'],
   },
-  // Grouped bubble corners — assistant (left side tight)
+  // Grouped bubble corners — assistant (inline-start side tight).
+  // Logical radii so the tail follows reading direction: inline-start is the
+  // left edge under LTR and the right edge under RTL (assistant tucks toward
+  // the start of the line in both directions).
   groupFirstAssistant: {
-    borderBottomLeftRadius: radiusVars['--radius-inner'],
+    borderEndStartRadius: radiusVars['--radius-inner'],
   },
   groupMiddleAssistant: {
-    borderTopLeftRadius: radiusVars['--radius-inner'],
-    borderBottomLeftRadius: radiusVars['--radius-inner'],
+    borderStartStartRadius: radiusVars['--radius-inner'],
+    borderEndStartRadius: radiusVars['--radius-inner'],
   },
   groupLastAssistant: {
-    borderTopLeftRadius: radiusVars['--radius-inner'],
+    borderStartStartRadius: radiusVars['--radius-inner'],
   },
-  // Grouped bubble corners — user (right side tight)
+  // Grouped bubble corners — user (inline-end side tight).
+  // Logical radii: inline-end is the right edge under LTR and the left edge
+  // under RTL (user tucks toward the end of the line in both directions).
   groupFirstUser: {
-    borderBottomRightRadius: radiusVars['--radius-inner'],
+    borderEndEndRadius: radiusVars['--radius-inner'],
   },
   groupMiddleUser: {
-    borderTopRightRadius: radiusVars['--radius-inner'],
-    borderBottomRightRadius: radiusVars['--radius-inner'],
+    borderStartEndRadius: radiusVars['--radius-inner'],
+    borderEndEndRadius: radiusVars['--radius-inner'],
   },
   groupLastUser: {
-    borderTopRightRadius: radiusVars['--radius-inner'],
+    borderStartEndRadius: radiusVars['--radius-inner'],
   },
 });
 

package/src/Chat/ChatSystemMessage.test.tsx

@@ -28,6 +28,11 @@ describe('ChatSystemMessage', () => {
     expect(screen.getByText('Today')).toBeTruthy();
   });
 
+  it('exposes the divider variant label as the separator accessible name', () => {
+    render(<ChatSystemMessage variant="divider">Today</ChatSystemMessage>);
+    expect(screen.getByRole('separator')).toHaveAccessibleName('Today');
+  });
+
   it('renders icon', () => {
     render(
       <ChatSystemMessage icon={<span data-testid="icon">*</span>}>

package/src/Chat/ChatToolCalls.tsx

@@ -37,6 +37,7 @@ import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -363,6 +364,7 @@ function getToolCallKey(call: ChatToolCallItem): string {
 // =============================================================================
 
 function CallRow({call}: {call: ChatToolCallItem}) {
+  const t = useTranslator();
   const status = call.status ?? 'complete';
   const hasDetail = call.resultDetail != null;
   const [isDetailOpen, setIsDetailOpen] = useState(false);
@@ -414,7 +416,11 @@ function CallRow({call}: {call: ChatToolCallItem}) {
           // 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>
+          <VisuallyHidden>
+            {t('@astryx.chatToolCalls.error', {
+              message: call.errorMessage ?? '',
+            })}
+          </VisuallyHidden>
         )}
       </span>
       <span {...stylex.props(styles.callName)}>{call.name}</span>
@@ -498,6 +504,7 @@ function CallRow({call}: {call: ChatToolCallItem}) {
  * ```
  */
 export function ChatToolCalls(props: ChatToolCallsProps) {
+  const t = useTranslator();
   const {
     calls,
     label: _customLabel,
@@ -580,7 +587,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
               <Icon icon="wrench" size="sm" color="inherit" />
             </span>
             <span {...stylex.props(styles.groupLabel)}>
-              {calls.length} tool calls
+              {t('@astryx.chatToolCalls.groupLabel', {count: calls.length})}
             </span>
           </>
         ) : (

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'],

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

@@ -13,6 +13,7 @@ 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 {getForcedColorsRules} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -543,3 +544,25 @@ describe('CheckboxInput', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so this asserts that the
+// compiled output includes the forced-colors rule; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles a forced-colors fill so the indeterminate mark survives Windows High Contrast', () => {
+    render(
+      <CheckboxInput label="All" value="indeterminate" onChange={() => {}} />,
+    );
+    // The painted indeterminate bar would be stripped to Canvas (invisible);
+    // CanvasText keeps it perceivable.
+    expect(getForcedColorsRules()).toContain('background-color: canvastext;');
+  });
+
+  it('compiles a forced-colors color so the checkmark survives Windows High Contrast', () => {
+    render(<CheckboxInput label="Accept" value={true} onChange={() => {}} />);
+    // The check strokes with currentColor; forced colors leaves it the same
+    // white as the flattened box, so it needs its own CanvasText color to stay
+    // perceivable on the Canvas box.
+    expect(getForcedColorsRules()).toContain('color: canvastext;');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -158,14 +158,29 @@ const styles = stylex.create({
   },
   checkmark: {
     display: 'none',
-    color: colorVars['--color-on-accent'],
+    color: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) does not reliably force an SVG
+      // stroke painted with currentColor, so the check stays the same white as
+      // the flattened (Canvas) box fill — a white check on a white box.
+      // CanvasText keeps it perceivable on the Canvas box, matching the
+      // indeterminate mark (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
   },
   checkmarkVisible: {
     display: 'block',
   },
   indeterminateMark: {
     display: 'none',
-    backgroundColor: colorVars['--color-on-accent'],
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the indeterminate bar invisible; CanvasText keeps it
+      // perceivable on the Canvas box fill (WCAG 1.4.11). The checkmark carries
+      // the matching CanvasText treatment on its own style.
+      '@media (forced-colors: active)': 'CanvasText',
+    },
     borderRadius: radiusVars['--radius-full'],
   },
   indeterminateMarkVisible: {
@@ -198,12 +213,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

@@ -154,14 +154,105 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
 
-    // Click the interactive row (invisible-button pattern), which is where the
-    // composed onClick lives — not the inner checkbox.
-    await user.click(screen.getByRole('button', {name: 'Option B'}));
+    // The row is a pointer-only click surface (no invisible row button — the
+    // checkbox is the option's only tab stop). Click the row's label area,
+    // where the composed onClick fires — not the inner checkbox.
+    expect(
+      screen.queryByRole('button', {name: 'Option B'}),
+    ).not.toBeInTheDocument();
+    // The text also exists in the checkbox's visually hidden <label>; target
+    // the row's label <span> to click the row surface.
+    await user.click(screen.getByText('Option B', {selector: 'span'}));
 
     expect(handleClick).toHaveBeenCalledTimes(1);
     expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
   });
 
+  describe('single tab stop per option (WCAG 4.1.2 / APG checkbox pattern)', () => {
+    it('renders exactly one focusable control per option — the checkbox, no row button', () => {
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // No invisible whole-row button duplicating the checkbox's action.
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      for (const item of screen.getAllByRole('listitem')) {
+        const focusables = item.querySelectorAll(
+          'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+        );
+        expect(focusables).toHaveLength(1);
+        expect(focusables[0]).toBe(within(item).getByRole('checkbox'));
+      }
+    });
+
+    it('Tab moves directly from one option checkbox to the next', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option A'})).toHaveFocus();
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option B'})).toHaveFocus();
+      // No further tab stop inside the list (the row itself is not focusable).
+      await user.tab();
+      expect(document.body).toHaveFocus();
+    });
+
+    it('clicking the row surface (outside the checkbox) still toggles', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // The text also exists in the checkbox's visually hidden <label>;
+      // target the row's label <span> to click the row surface.
+      await user.click(screen.getByText('Option B', {selector: 'span'}));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+
+    it('toggles with Space on the focused checkbox, which reports checked state', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      // The focused control is the checkbox itself, so its accessible name
+      // and checked state are what assistive tech announces on focus.
+      const checkboxA = screen.getByRole('checkbox', {name: 'Option A'});
+      expect(checkboxA).toHaveFocus();
+      expect(checkboxA).toBeChecked();
+      await user.keyboard(' ');
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith([]);
+    });
+
+    it('the row itself is not focusable', () => {
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+        </CheckboxList>,
+      );
+      const item = screen.getByRole('listitem');
+      expect(item).not.toHaveAttribute('tabindex');
+      item.focus();
+      expect(item).not.toHaveFocus();
+    });
+  });
+
   it('disables all checkboxes when group isDisabled is true', () => {
     render(
       <CheckboxList

package/src/CheckboxList/CheckboxListItem.tsx

@@ -16,12 +16,11 @@
  * - /packages/cli/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, type MouseEvent, type ReactNode} from 'react';
+import {use, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 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';
@@ -212,6 +211,14 @@ export function CheckboxListItem({
   // Whether this item is interactive (has a toggle handler)
   const isInteractive = !effectiveReadOnly && (ctx != null || onCheck != null);
 
+  // The checkbox is the row's single keyboard control and action. The row is
+  // an enlarged click/tap target that delegates surface clicks to it via
+  // ListItem's `interactiveRef` (useClickableContainer), so each option is
+  // exactly one tab stop. Delegate whenever the row should respond to clicks:
+  // a toggleable item, or one carrying a consumer `onClick`.
+  const checkboxRef = useRef<HTMLInputElement | null>(null);
+  const hasRowInteraction = isInteractive || onClickProp != null;
+
   const handleToggle = () => {
     if (effectiveDisabled || effectiveReadOnly || isBusy) {
       return;
@@ -244,14 +251,12 @@ export function CheckboxListItem({
       description={description}
       endContent={endContent}
       isDisabled={effectiveDisabled}
-      onClick={
-        isInteractive || onClickProp
-          ? composeEventHandlers<MouseEvent>(
-              onClickProp as ((event: MouseEvent) => void) | undefined,
-              isInteractive ? handleToggle : undefined,
-            )
-          : undefined
-      }
+      // Delegate row clicks to the checkbox instead of wiring onClick (which
+      // would add an invisible row button = a second tab stop). The checkbox
+      // stays the option's sole focusable control (WCAG 4.1.2 / APG checkbox
+      // pattern). A consumer onClick rides on the checkbox itself (below), so
+      // it still fires for both direct and delegated (row-surface) clicks.
+      interactiveRef={hasRowInteraction ? checkboxRef : undefined}
       aria-busy={isBusy || undefined}
       xstyle={
         [
@@ -266,10 +271,12 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <CheckboxInput
+          ref={checkboxRef}
           label={checkboxLabel}
           isLabelHidden
           value={resolvedChecked}
           onChange={() => handleToggle()}
+          onClick={onClickProp}
           isDisabled={effectiveDisabled}
           isReadOnly={effectiveReadOnly}
           isLoading={isBusy}

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.',
   },