@astryxdesign/core 0.3.0 → 0.4.0

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -9,13 +9,21 @@ export const docs = {
   keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -68,13 +76,21 @@ export const docsZh = {
   displayName: 'Aspect Ratio',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -110,13 +126,21 @@ export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   propDescriptions: {

package/src/AspectRatio/AspectRatio.test.tsx

@@ -276,6 +276,36 @@ describe('AspectRatio', () => {
     });
   });
 
+  describe('style merging', () => {
+    it('keeps the consumer style and applies the ratio over it', () => {
+      render(
+        <AspectRatio
+          ratio={16 / 9}
+          data-testid="aspect-ratio"
+          style={{opacity: 0.5, aspectRatio: '3 / 1'}}>
+          <div>Content</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      expect(element.style.opacity).toBe('0.5');
+      expect(element.style.aspectRatio).toBe(String(16 / 9));
+    });
+
+    it('keeps a consumer className beside the theme target', () => {
+      render(
+        <AspectRatio
+          ratio={1}
+          data-testid="aspect-ratio"
+          className="consumer-class">
+          <div>Content</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      expect(element).toHaveClass('consumer-class');
+      expect(element).toHaveClass('astryx-aspect-ratio');
+    });
+  });
+
   describe('reset.css fit baseline rules', () => {
     // The cover/contain child sizing ships as zero-specificity baseline
     // rules in reset.css keyed on the data-astryx-aspect-ratio-override

package/src/AspectRatio/AspectRatio.tsx

@@ -94,6 +94,10 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   /**
    * Content to render inside the aspect ratio container.
    * The child element will be positioned absolutely to fill the container.
+   *
+   * Pass a single child. With `fit` set, every direct child is stretched to
+   * fill the box, so a second child is laid out below the first and clipped
+   * out of view; compose an overlay or caption inside one wrapper child.
    */
   children: ReactNode;
 }
@@ -145,6 +149,15 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * Sizing: the box takes its width from its container and derives its height
+ * from the ratio, so it needs an ancestor with a definite width. Two
+ * consequences are worth knowing. Constraining only the height (`height` or
+ * `maxHeight`) clamps the box without releasing the width, so the rendered
+ * ratio no longer matches `ratio`; pass `width: 'auto'` alongside to size from
+ * the height instead. And in a shrink-to-fit parent (`inline-flex`,
+ * `width: fit-content`, a floated box) it contributes no intrinsic width and
+ * collapses to zero.
+ *
  * @example
  * ```
  * <AspectRatio ratio={16 / 9} fit="cover">

package/src/Avatar/Avatar.doc.mjs

@@ -29,21 +29,10 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-avatar', visualProps: ['size']},
+      {className: 'astryx-avatar-fallback', visualProps: ['size']},
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
       {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
-    vars: [
-      {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},
-      {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},
-      {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},
-      {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},
-    ],
-    derived: [
-      {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
-      {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
-      {property: 'color', vars: ['--_avatar-fallback-color']},
-      {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
-    ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
   props: [
@@ -104,7 +93,7 @@ export const docs = {
       name: 'as',
       type: 'ElementType',
       description:
-        'Custom link component used when `href` is set (e.g. Next.js `Link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
+        'Custom link component used when `href` is set (e.g. `next/link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
     },
     {
       name: 'target',

package/src/Avatar/Avatar.test.tsx

@@ -37,17 +37,42 @@ describe('Avatar', () => {
     expect(innerImg).toHaveAttribute('alt', '');
   });
 
-  it('renders fallback initials through the themeable font-size var, not a bare px literal', () => {
+  it('renders fallback initials at the proportional size via a StyleX class, not an inline property', () => {
     render(<Avatar name="Ada Lovelace" size="sm" data-testid="a" />);
     const initials = screen.getByText('AL');
-    // The seam: the dynamic font size resolves to the Avatar-scoped var (with
-    // the proportional `size × 0.4` default baked in as the fallback), so a
-    // theme can re-scope it per size. A regression to a bare px literal would
-    // break theming.
+    // The default proportional size (sm = 24 × 0.4 = 9.6px) is fed to StyleX as
+    // a dynamic value: StyleX applies `font-size` through a class and sets only
+    // the computed value inline (as a custom property). Because the property
+    // lands via a class, a theme's `.astryx-avatar-fallback.<size>` rule in the
+    // theme layer overrides it per size tier — no internal var seam needed.
     const style = initials.getAttribute('style') ?? '';
-    expect(style).toContain('var(--_avatar-fallback-font-size,');
-    // Default still reproduces the proportional scale (sm = 24 × 0.4 = 9.6px).
-    expect(style).toMatch(/var\(--_avatar-fallback-font-size,\s*9\.6\d*px\)/);
+    expect(style).toMatch(/9\.6\d*px/);
+    // Regression guard: the seam must NOT reintroduce the removed internal var.
+    expect(style).not.toContain('--_avatar-fallback-font-size');
+  });
+
+  it('marks the fallback surface with the stable theming class (initials and icon)', () => {
+    // The background is themed directly on `.astryx-avatar-fallback`, so both
+    // the initials and the default-icon fallback must carry the class.
+    const {rerender} = render(<Avatar name="Ada Lovelace" />);
+    expect(screen.getByText('AL').className).toContain(
+      'astryx-avatar-fallback',
+    );
+
+    rerender(<Avatar />);
+    const icon = document.querySelector('.astryx-avatar-fallback');
+    expect(icon).not.toBeNull();
+    expect(icon?.querySelector('svg')).not.toBeNull();
+  });
+
+  it('does not split an emoji surrogate pair when generating initials', () => {
+    render(<Avatar name="😀 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('😀A');
+  });
+
+  it('preserves a complete grapheme when generating initials', () => {
+    render(<Avatar name="🇬🇧 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('🇬🇧A');
   });
 
   it('retries a new src after a previous src failed to load', () => {

package/src/Avatar/Avatar.tsx

@@ -31,6 +31,7 @@ import {AvatarSizeContext} from './AvatarSizeContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
@@ -112,9 +113,9 @@ const styles = stylex.create({
     display: 'inline-flex',
     flexShrink: 0,
     // The wrapper is not clipped (so the status dot can overflow), so it must be
-    // rounded itself: a themed fallback background lands on `.astryx-avatar` (the
-    // class-bearing wrapper) as well as the internal var, and an unrounded
-    // wrapper would show that fill as square corners behind the circular content.
+    // rounded itself: a theme can set a background on the `.astryx-avatar`
+    // wrapper, and an unrounded wrapper would show that fill as square corners
+    // behind the circular content.
     borderRadius: radiusVars['--radius-full'],
   },
   content: {
@@ -136,14 +137,15 @@ const styles = stylex.create({
     justifyContent: 'center',
     width: '100%',
     height: '100%',
-    // Fallback surface (initials + default icon). Each property reads an
-    // Avatar-scoped internal var so a theme can re-scope the fallback wash and
-    // initials weight/color without forking; the defaults reproduce today's
-    // exact output. See derivedVarRegistry (avatar) + Avatar.doc.mjs theming.
-    backgroundColor: `var(--_avatar-fallback-background, ${colorVars['--color-neutral']})`,
-    color: `var(--_avatar-fallback-color, ${colorVars['--color-text-secondary']})`,
+    // Fallback surface (initials + default icon). Background, text color,
+    // weight, and per-size font size are all themed directly via the stable
+    // `.astryx-avatar-fallback` class target (font size through its size
+    // variant, `.astryx-avatar-fallback.<size>`), so the defaults here are
+    // plain values with no internal-var seam. See Avatar.doc.mjs theming.
+    backgroundColor: colorVars['--color-neutral'],
+    color: colorVars['--color-text-secondary'],
     fontFamily: typographyVars['--font-family-body'],
-    fontWeight: `var(--_avatar-fallback-font-weight, ${fontWeightVars['--font-weight-medium']})`,
+    fontWeight: fontWeightVars['--font-weight-medium'],
     textTransform: 'uppercase',
   },
   status: {
@@ -152,16 +154,6 @@ const styles = stylex.create({
   // Visible focus ring for the name-tooltip tab stop, matching the repo-wide
   // focus-visible outline treatment (see Timestamp, Token, Thumbnail). Only
   // applied when a tooltip is active so keyboard users can reveal it.
-  focusable: {
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
   // Reset the intrinsic styling of the interactive element (<a>/<button>) so it
   // is a transparent, correctly-sized wrapper around the avatar visuals. The
   // element carries the focus-visible accent ring for keyboard users.
@@ -178,22 +170,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     // Match the avatar's circular shape so the focus ring hugs it.
     borderRadius: radiusVars['--radius-full'],
-    outlineWidth: {
-      default: 0,
-      ':focus-visible': 2,
-    },
-    outlineStyle: {
-      default: 'none',
-      ':focus-visible': 'solid',
-    },
-    outlineColor: {
-      default: null,
-      ':focus-visible': colorVars['--color-accent'],
-    },
-    outlineOffset: {
-      default: 0,
-      ':focus-visible': 2,
-    },
   },
 });
 
@@ -205,13 +181,12 @@ const dynamicStyles = stylex.create({
     width: size,
     height: size,
   }),
-  // Initials font size defaults to the proportional `size × ratio` scale but is
-  // reachable via the `--_avatar-fallback-font-size` derived var, so a theme can
-  // set a per-size type scale (e.g. `components.avatar['size:sm']`).
+  // Initials font size defaults to the proportional `size × ratio` scale. It's
+  // a StyleX dynamic style, so the value lands via a class (not an inline
+  // property) — a theme's `.astryx-avatar-fallback.<size>` rule in the theme
+  // layer overrides it per size tier, no internal var needed.
   fontSize: (size: number) => ({
-    fontSize: `var(--_avatar-fallback-font-size, ${
-      size * INITIALS_FONT_SIZE_RATIO
-    }px)`,
+    fontSize: `${size * INITIALS_FONT_SIZE_RATIO}px`,
   }),
   statusPosition: (size: number) => ({
     bottom: size * CIRCLE_EDGE_OFFSET_RATIO,
@@ -337,6 +312,25 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
   onClick?: React.MouseEventHandler<HTMLElement>;
 }
 
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ */
+const graphemeSegmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
+    : null;
+
+/**
+ * Return the first user-perceived character, with a code-point fallback.
+ */
+function firstGrapheme(word: string): string {
+  if (graphemeSegmenter) {
+    return [...graphemeSegmenter.segment(word)][0]?.segment ?? '';
+  }
+
+  return [...word][0] ?? '';
+}
+
 /**
  * Generates initials from a name string.
  * Takes the first letter of the first two words.
@@ -352,9 +346,11 @@ function getInitials(name: string): string {
     return '';
   }
   if (words.length === 1) {
-    return words[0].charAt(0).toUpperCase();
+    return firstGrapheme(words[0]).toUpperCase();
   }
-  return (words[0].charAt(0) + words[words.length - 1].charAt(0)).toUpperCase();
+  return (
+    firstGrapheme(words[0]) + firstGrapheme(words[words.length - 1])
+  ).toUpperCase();
 }
 
 /**
@@ -549,15 +545,22 @@ export function Avatar({
         )}
         {showInitials && (
           <div
-            {...stylex.props(
-              styles.fallback,
-              dynamicStyles.fontSize(numericSize),
+            {...mergeProps(
+              themeProps('avatar-fallback', {size: resolvedSize}),
+              stylex.props(
+                styles.fallback,
+                dynamicStyles.fontSize(numericSize),
+              ),
             )}>
             {getInitials(name)}
           </div>
         )}
         {showIcon && (
-          <div {...stylex.props(styles.fallback)}>
+          <div
+            {...mergeProps(
+              themeProps('avatar-fallback', {size: resolvedSize}),
+              stylex.props(styles.fallback),
+            )}>
             <DefaultIcon size={numericSize} />
           </div>
         )}
@@ -580,10 +583,9 @@ export function Avatar({
   // `<a>`/`<button>` and the static `<div>` carry the exact same box.
   const rootStylexProps = mergeProps(
     themeProps('avatar', {size: resolvedSize}),
-    stylex.props(
+    focusOutlineProps.focusVisible(
       styles.wrapper,
       isInteractive && styles.interactive,
-      !isInteractive && showTooltip && !avatarGroup && styles.focusable,
       avatarGroup && groupStyles.ring,
       avatarGroup && groupStyles.overlap,
       avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -26,6 +26,7 @@ import {mergeProps} from '../utils';
 import {useAvatarGroup} from './AvatarGroupContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 const BORDER_WIDTH = 2;
@@ -93,14 +94,6 @@ const styles = stylex.create({
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']}), linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
     },
     // Focus ring via focus-visible
-    outline: {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: null,
-      ':focus-visible': '2px',
-    },
   },
   overlap: {
     marginInlineStart: 'var(--_avatar-group-overlap)',
@@ -170,7 +163,7 @@ export function AvatarGroupOverflow({
         data-avatar-item=""
         {...mergeProps(
           themeProps('avatar-group-overflow'),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.base,
             styles.button,
             styles.overlap,

package/src/Banner/Banner.tsx

@@ -271,8 +271,9 @@ const styles = stylex.create({
     borderEndStartRadius: radiusVars['--radius-container'],
     borderEndEndRadius: radiusVars['--radius-container'],
   },
+  // Applied to the chevron <Icon> itself (via `xstyle`) rather than a wrapper,
+  // so the element that rotates is the element a theme targets.
   chevron: {
-    display: 'inline-flex',
     transitionProperty: 'transform',
     transitionDuration: {
       default: durationVars['--duration-fast'],
@@ -484,13 +485,15 @@ export function Banner({
                     : t('@astryx.banner.expand')
                 }
                 icon={
-                  <span
-                    {...stylex.props(
+                  <Icon
+                    icon="chevronDown"
+                    size="sm"
+                    color="inherit"
+                    xstyle={[
                       styles.chevron,
                       isExpanded && styles.chevronExpanded,
-                    )}>
-                    <Icon icon="chevronDown" size="sm" color="inherit" />
-                  </span>
+                    ]}
+                  />
                 }
                 onClick={handleToggleExpand}
                 aria-expanded={isExpanded}

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -45,7 +45,7 @@ import type {LinkComponentType} from '../Link/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {usePopover} from '../Popover/usePopover';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
@@ -196,6 +196,11 @@ const itemStyles = stylex.create({
     display: 'flex',
     alignItems: 'center',
     flexShrink: 0,
+    // Sized off supporting text (12px) — exactly Icon's `xsm` box at the
+    // default type scale. Width/height stay on the token so the box and the
+    // glyph keep matching if a theme retunes the supporting step.
+    width: typeScaleVars['--text-supporting-size'],
+    height: typeScaleVars['--text-supporting-size'],
     fontSize: typeScaleVars['--text-supporting-size'],
   },
   separator: {
@@ -507,8 +512,6 @@ function BreadcrumbMenuTrigger({
     role: 'none',
   });
 
-  const chevronDownIcon = useIcon('chevronDown');
-
   const closeMenu = useCallback(() => {
     popover.hide();
   }, [popover]);
@@ -624,9 +627,16 @@ function BreadcrumbMenuTrigger({
           isSupporting ? itemStyles.supportingLink : itemStyles.defaultLink,
         )}>
         {children}
-        <span aria-hidden="true" {...stylex.props(itemStyles.chevron)}>
-          {chevronDownIcon}
-        </span>
+        <Icon
+          icon="chevronDown"
+          // 0.75rem — the 12px supporting-text box the bare glyph already
+          // rendered at; `itemStyles.chevron` keeps that box on the token.
+          size="xsm"
+          // The chevron reads as part of the link label, so it takes the
+          // trigger's link color rather than an icon color.
+          color="inherit"
+          xstyle={itemStyles.chevron}
+        />
       </button>
 
       {popover.render(

package/src/Breadcrumbs/index.ts

@@ -37,6 +37,10 @@ export {
   DropdownMenuItem as BreadcrumbMenuItem,
   type DropdownMenuItemProps as BreadcrumbMenuItemProps,
 } from '../DropdownMenu/DropdownMenuItem';
+export {
+  DropdownMenuDivider as BreadcrumbMenuDivider,
+  type DropdownMenuDividerProps as BreadcrumbMenuDividerProps,
+} from '../DropdownMenu/DropdownMenuDivider';
 export {
   DropdownMenuCheckboxItem as BreadcrumbMenuCheckboxItem,
   type DropdownMenuCheckboxItemProps as BreadcrumbMenuCheckboxItemProps,
@@ -56,6 +60,6 @@ export {
 export type {
   DropdownMenuOption as BreadcrumbMenuOption,
   DropdownMenuItemData as BreadcrumbMenuItemData,
-  DropdownMenuDivider as BreadcrumbMenuDivider,
+  DropdownMenuDividerData as BreadcrumbMenuDividerData,
   DropdownMenuSection as BreadcrumbMenuSection,
 } from '../DropdownMenu/DropdownMenu';