@astryxdesign/core 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

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/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/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/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.tsx

@@ -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/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');
+  });
 });

package/src/Citation/Citation.tsx

@@ -10,10 +10,14 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Citation/index.ts (exports if types change)
+ * - /packages/core/src/Citation/Citation.doc.mjs (props table, features)
+ * - /packages/core/src/Citation/Citation.test.tsx (tests for new/changed behavior)
+ * - /apps/storybook/stories/Citation.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)
  */
 
 import type React from 'react';
+import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -29,11 +33,29 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {renderIconSlot} from '../Icon';
 
 export interface CitationSource {
   title?: string;
   url?: string;
-  icon?: string;
+  /**
+   * Image URL for a favicon or source logo, rendered as `<img src>` inside the
+   * icon circle. This is the idiomatic field for image sources (mirrors
+   * `Avatar`/`Thumbnail` `src`). When both `src` and a non-string `icon` are
+   * provided, `icon` wins.
+   */
+  src?: string;
+  /**
+   * Source icon shown before the label text (label variant only). Accepts:
+   * - a React node / Astryx `<Icon>` / SVG element — rendered as-is, or
+   * - a string image URL — rendered as `<img src>` for backward compatibility
+   *   with callers that passed a favicon URL here.
+   *
+   * Note: unlike icon slots elsewhere in the system, a bare string is treated
+   * as an image URL (not a semantic icon name) to preserve the original
+   * favicon behavior. Pass an Astryx `<Icon>` (or other node) for a real icon.
+   */
+  icon?: ReactNode;
 }
 
 export interface CitationProps extends BaseProps<HTMLElement> {
@@ -162,7 +184,18 @@ export function Citation({
   const t = useTranslator();
   const title = source.title ?? String(number);
   const href = source.url;
-  const icon = source.icon;
+
+  // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
+  // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or
+  // a legacy string passed to `icon` (back-compat — favicon URLs still render
+  // as <img>). The icon is decorative; the accessible name comes solely from
+  // the element's aria-label, so nothing is double-announced.
+  const iconNode =
+    source.icon != null && typeof source.icon !== 'string' ? source.icon : null;
+  const imageSrc =
+    source.src ?? (typeof source.icon === 'string' ? source.icon : undefined);
+  const hasIcon = iconNode != null || imageSrc != null;
+
   const Tag = href ? 'a' : 'span';
   // `doc-noteref` is a reference role — only appropriate on the interactive
   // link form. On a plain (unlinked) span it is not a permitted role
@@ -218,7 +251,7 @@ export function Citation({
         themeProps('citation', {variant}),
         stylex.props(
           styles.label,
-          icon != null && styles.labelWithIcon,
+          hasIcon && styles.labelWithIcon,
           href != null && styles.labelHover,
           href != null && styles.labelInteractive,
           xstyle,
@@ -226,14 +259,13 @@ export function Citation({
         className,
         style,
       )}>
-      {icon && (
-        <span {...stylex.props(styles.iconWrap)}>
-          <img
-            src={icon}
-            alt=""
-            aria-hidden="true"
-            {...stylex.props(styles.icon)}
-          />
+      {hasIcon && (
+        <span aria-hidden="true" {...stylex.props(styles.iconWrap)}>
+          {iconNode != null ? (
+            renderIconSlot(iconNode, {size: 'sm'})
+          ) : (
+            <img src={imageSrc} alt="" {...stylex.props(styles.icon)} />
+          )}
         </span>
       )}
       <span {...stylex.props(styles.labelText)}>{title}</span>

package/src/CodeBlock/CodeBlock.tsx

@@ -88,6 +88,23 @@ const dynamicStyles = stylex.create({
   }),
 });
 
+// Light reveal so the leading chevron eases into view instead of popping in.
+// Growing the chevron's own footprint (width + inline margin) from zero slides
+// the title into place instead of snapping it over, and clipping keeps the
+// glyph from spilling while it's mid-reveal.
+const chevronReveal = stylex.keyframes({
+  from: {
+    width: 0,
+    marginInlineEnd: 0,
+    opacity: 0,
+  },
+  to: {
+    width: '14px',
+    marginInlineEnd: spacingVars['--spacing-1'],
+    opacity: 1,
+  },
+});
+
 const styles = stylex.create({
   root: {
     position: 'relative',
@@ -133,7 +150,6 @@ const styles = stylex.create({
   headerTitle: {
     display: 'flex',
     alignItems: 'center',
-    gap: spacingVars['--spacing-1'],
     fontSize: typeScaleVars['--text-supporting-size'],
     fontFamily: typographyVars['--font-family-code'],
     fontWeight: fontWeightVars['--font-weight-medium'],
@@ -173,13 +189,24 @@ const styles = stylex.create({
     flexShrink: 0,
     width: '14px',
     height: '14px',
+    marginInlineEnd: spacingVars['--spacing-1'],
+    overflow: 'hidden',
     color: 'var(--color-syntax-comment)',
+    animationName: {
+      default: chevronReveal,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationDuration: durationVars['--duration-medium'],
+    animationTimingFunction: easeVars['--ease-standard'],
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
-  collapseChevronCollapsed: {
-    transform: 'rotate(180deg)',
+  collapseChevronExpanded: {
+    // Leading disclosure convention (matches TreeList/Table): the resting
+    // chevronRight points right (>) when collapsed; rotate it down (v) when
+    // expanded.
+    transform: 'rotate(90deg)',
   },
   headerCollapsible: {
     cursor: 'pointer',
@@ -845,18 +872,18 @@ export function CodeBlock({
           canCollapse && styles.headerCollapsible,
         )}>
         <span {...stylex.props(styles.headerTitle)}>
-          {title}
-          {title && languageLabel ? ' — ' : ''}
-          {languageLabel}
           {canCollapse && (
             <span
               {...stylex.props(
                 styles.collapseChevron,
-                isCollapsed && styles.collapseChevronCollapsed,
+                !isCollapsed && styles.collapseChevronExpanded,
               )}>
-              <Icon icon="chevronDown" size="xsm" color="inherit" />
+              <Icon icon="chevronRight" size="xsm" color="inherit" />
             </span>
           )}
+          {title}
+          {title && languageLabel ? ' — ' : ''}
+          {languageLabel}
         </span>
       </div>
       {copyButtonEl}

package/src/Collapsible/Collapsible.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-collapsible', visualProps: ['density']},
+      {className: 'astryx-collapsible-trigger', visualProps: ['density']},
       {className: 'astryx-collapsible-content', visualProps: ['density']},
       {className: 'astryx-collapsible-group', visualProps: ['density']},
     ],

package/src/Collapsible/Collapsible.test.tsx

@@ -72,6 +72,13 @@ describe('Collapsible', () => {
       expect(screen.getByTestId('root')).toHaveClass('astryx-collapsible');
     });
 
+    it('renders the stable astryx-collapsible-trigger class on the trigger button', () => {
+      render(<Collapsible trigger="T">c</Collapsible>);
+      expect(screen.getByRole('button')).toHaveClass(
+        'astryx-collapsible-trigger',
+      );
+    });
+
     it('renders the stable astryx-collapsible-content class on the content area', () => {
       render(<Collapsible trigger="T">c</Collapsible>);
       const content = contentFor(screen.getByRole('button'));

package/src/Collapsible/Collapsible.tsx

@@ -51,7 +51,12 @@ const styles = stylex.create({
   root: {
     width: '100%',
   },
-  // Trigger button — full width, flex row, no browser button styling
+  // Trigger button — full width, flex row, no browser button styling.
+  // Anchors heading-adjacent typography (body family, large size, semibold)
+  // so the label reads as a section header regardless of where the
+  // Collapsible is placed. External themes retarget it independently from the
+  // content via the `astryx-collapsible-trigger` target — e.g. a heading font
+  // on the trigger while the content stays on the body font.
   trigger: {
     all: 'unset',
     boxSizing: 'border-box',
@@ -113,7 +118,7 @@ const styles = stylex.create({
   // Anchors body typography so revealed text renders at the system's body
   // scale (family/size/weight/leading) instead of inheriting from wherever
   // the Collapsible is placed. External themes override via the
-  // `astryx-collapsible-content` target.
+  // `astryx-collapsible-content` target, independently from the trigger.
   content: {
     paddingBlockStart: spacingVars['--spacing-1'],
     fontFamily: typographyVars['--font-family-body'],
@@ -318,10 +323,15 @@ export function Collapsible({
         // the system-wide disabled convention (never native `disabled`, which
         // would swallow events like a wrapping tooltip's hover).
         tabIndex={isDisabled ? -1 : undefined}
-        {...stylex.props(
-          styles.trigger,
-          density != null && triggerDensity[density],
-          isDisabled && styles.triggerDisabled,
+        {...mergeProps(
+          themeProps('collapsible-trigger', {
+            density: density ?? undefined,
+          }),
+          stylex.props(
+            styles.trigger,
+            density != null && triggerDensity[density],
+            isDisabled && styles.triggerDisabled,
+          ),
         )}>
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
         <span