@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

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

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file AspectRatio.tsx
  * @input Uses React, stylex
@@ -94,6 +92,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 +147,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/AspectRatio/index.ts

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports from AspectRatio.tsx

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

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file Badge.tsx
  * @input Uses React, HTMLAttributes

package/src/Badge/index.ts

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports Badge component and types from Badge.tsx

package/src/Banner/Banner.test.tsx

@@ -3,7 +3,8 @@
 /**
  * @file Banner.test.tsx
  * @input Uses vitest, @testing-library/react, Banner component
- * @output Unit tests for Banner component behavior
+ * @output Unit tests for Banner component behavior, including the
+ *   'banner-icon' theme target riding on the status icon glyph (#4166)
  * @position Testing; validates Banner.tsx implementation
  *
  * SYNC: When modified, update this header
@@ -337,6 +338,62 @@ describe('Banner', () => {
     expect(ref.current).toBeInstanceOf(HTMLDivElement);
   });
 
+  // =========================================================================
+  // Status icon color theming (#4166)
+  // =========================================================================
+
+  it("carries the 'banner-icon' theme target on the default status icon glyph", () => {
+    // Theme overrides for 'banner-icon' + 'status:X' compile to
+    // '.astryx-banner-icon.<status>' (parseStyleKey). The target must sit on
+    // the <Icon> span itself so those same-element rules in
+    // @layer astryx-theme beat the Icon's own color variant.
+    const statuses = ['info', 'warning', 'error', 'success'] as const;
+    for (const status of statuses) {
+      const {container, unmount} = render(
+        <Banner status={status} title={`${status} banner`} />,
+      );
+      const glyph = container.querySelector(
+        `.astryx-icon.astryx-banner-icon.${status}`,
+      );
+      expect(glyph).not.toBeNull();
+      expect(glyph).toHaveAttribute('data-status', status);
+      // Exactly one element carries the target — the layout wrapper no
+      // longer does.
+      expect(container.querySelectorAll('.astryx-banner-icon')).toHaveLength(1);
+      unmount();
+    }
+  });
+
+  it('keeps the color variant on the theme-target element (regression pin for #4166)', () => {
+    // Pre-fix, '.astryx-banner-icon.info' matched the layout wrapper while
+    // the color variant (data-color="accent") sat on an inner span that a
+    // theme override could never reach. Target and paint now share one
+    // element.
+    const {container} = render(<Banner status="info" title="Info" />);
+    const target = container.querySelector('.astryx-banner-icon.info');
+    expect(target).toHaveAttribute('data-color', 'accent');
+  });
+
+  it("keeps the 'banner-icon' target on the wrapper for a custom icon node", () => {
+    // Core never injects props into consumer elements, so with a custom
+    // `icon` the target stays on the (layout-only) wrapper and overrides
+    // reach the node via inheritance. The node itself is untouched.
+    const {container} = render(
+      <Banner
+        status="info"
+        title="Custom icon"
+        icon={<span data-testid="custom-glyph">i</span>}
+      />,
+    );
+    const targets = container.querySelectorAll('.astryx-banner-icon');
+    expect(targets).toHaveLength(1);
+    expect(targets[0]?.tagName).toBe('DIV');
+    expect(targets[0]).toHaveAttribute('aria-hidden', 'true');
+    const custom = container.querySelector('[data-testid="custom-glyph"]');
+    expect(custom).not.toBeNull();
+    expect(custom?.className).toBe('');
+  });
+
   // =========================================================================
   // Icon registry integration
   // =========================================================================

package/src/Banner/Banner.tsx

@@ -12,6 +12,9 @@
  * - Root container: layout-only wrapper (flex column), no visual styling, no theme target
  * - Header area (themeProps 'banner'): colored status background with icon, title, description, actions, dismiss
  * - Content area (themeProps 'banner-content'): collapsible card background for additional content (children)
+ * - Status icon (themeProps 'banner-icon'): the target rides on the default
+ *   <Icon> itself — the element that paints — so 'status:X' overrides reach
+ *   the glyph (#4166); for a custom `icon` node it stays on the layout wrapper
  * - No left border accent — color is expressed through the full header background
  * - Each visual area owns its own border-radius (no overflow:clip on the container)
  * - When children are provided, a collapse/expand toggle button appears in the end area
@@ -271,8 +274,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'],
@@ -444,16 +448,32 @@ export function Banner({
                 : styles.headerCardStandalone),
           ),
         )}>
+        {/* The 'banner-icon' target rides on the element that paints: the
+            default <Icon> below, or this wrapper when a custom `icon` node
+            is passed (core never injects props into consumer elements, so
+            overrides reach it via inheritance). The wrapper itself stays
+            layout-only. */}
         <div
-          {...mergeProps(
-            themeProps('banner-icon', {status}),
-            stylex.props(styles.iconWrapper),
-          )}
+          {...(icon != null
+            ? mergeProps(
+                themeProps('banner-icon', {status}),
+                stylex.props(styles.iconWrapper),
+              )
+            : stylex.props(styles.iconWrapper))}
           aria-hidden="true">
           {icon != null ? (
             icon
           ) : (
-            <Icon icon={defaultIconName} size="md" color={iconColor} />
+            // Applied to the status <Icon> itself rather than the wrapper, so
+            // the element that paints the glyph is the element a theme
+            // targets — a 'banner-icon' 'status:X' color override beats the
+            // Icon's own variant from @layer astryx-theme (#4166).
+            <Icon
+              icon={defaultIconName}
+              size="md"
+              color={iconColor}
+              {...themeProps('banner-icon', {status})}
+            />
           )}
         </div>
         <div {...stylex.props(styles.headerContent)}>
@@ -484,13 +504,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/Blockquote/Blockquote.tsx

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file Blockquote.tsx
  * @input Uses React, stylex, spacing and color tokens

package/src/Blockquote/index.ts

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports from Blockquote.tsx

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';

package/src/Button/Button.doc.mjs

@@ -163,7 +163,7 @@ export const docs = {
     ],
     vars: [
       {name: '--_button-radius', description: 'Border radius', default: 'var(--radius-element)', private: true},
-      {name: '--button-focus-offset', description: 'Focus ring outline offset', default: '3px'},
+      {name: '--button-focus-offset', description: 'Focus ring outline offset', default: 'var(--focus-outline-offset)'},
       {name: '--button-icon-only-aspect', description: 'Aspect ratio for icon-only buttons', default: '1 / 1'},
     ],
     derived: [
@@ -245,7 +245,7 @@ export const docsZh = {
     ],
     vars: [
       {name: '--_button-radius', description: '圆角半径', default: 'var(--radius-element)', private: true},
-      {name: '--button-focus-offset', description: '焦点环轮廓偏移', default: '3px'},
+      {name: '--button-focus-offset', description: '焦点环轮廓偏移', default: 'var(--focus-outline-offset)'},
       {name: '--button-icon-only-aspect', description: '纯图标按钮的宽高比', default: '1 / 1'},
     ],
     derived: [