@astryxdesign/core 0.3.0 → 0.4.0-canary.41f53a0

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

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: [

package/src/Button/Button.tsx

@@ -34,6 +34,7 @@ import {
   fontWeightVars,
   typeScaleVars,
   shadowVars,
+  focusVars,
 } from '../theme/tokens.stylex';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -45,6 +46,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 import type {ButtonVariantMap} from './index';
 
@@ -55,6 +57,15 @@ import type {ButtonVariantMap} from './index';
  */
 const styles = stylex.create({
   base: {
+    // Kept as a public themeable var (documented in Button.doc.mjs) even though
+    // it now defaults to the shared token: removing it would break any theme
+    // setting it, for no gain. It overrides the shared offset, so a theme can
+    // still tune the ring distance on buttons specifically.
+    '--button-focus-offset': focusVars['--focus-outline-offset'],
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': 'var(--button-focus-offset)',
+    },
     position: 'relative',
     display: 'inline-flex',
     alignItems: 'center',
@@ -179,7 +190,7 @@ const elevationStyles = stylex.create({
  * Variant styles using backgroundImage for layered colors
  * Pseudo-classes are nested within properties per StyleX recommendation
  * Overlay is stacked on top of base color using multiple linear-gradients
- * Focus outline color matches variant (destructive uses negative color)
+ * Focus outline is shared across variants for consistent keyboard affordance.
  */
 const variants = stylex.create({
   primary: {
@@ -192,15 +203,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   secondary: {
     backgroundColor: colorVars['--color-neutral'],
@@ -212,15 +214,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   ghost: {
     backgroundColor: 'transparent',
@@ -232,19 +225,14 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   destructive: {
     backgroundColor: colorVars['--color-error'],
     color: colorVars['--color-on-error'],
+    // The ring matches the variant it rings: an accent-colored outline on a
+    // red button reads as another control's focus. Only the color differs —
+    // width, style and offset come from the shared outline.
+    outlineColor: {default: null, ':focus-visible': colorVars['--color-error']},
     backgroundImage: {
       default: null,
       ':hover': {
@@ -252,15 +240,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-error']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
 });
 
@@ -676,10 +655,9 @@ export function Button({
   const edgeCompAttr = isFlat ? {[EDGE_COMP_ATTR]: ''} : null;
 
   // Shared StyleX props for both button and link rendering
-  const sharedStylexProps = stylex.props(
+  const sharedStylexProps = focusOutlineProps.focusVisible(
     styles.base,
     sizeStyles[size],
-    variants[variant],
     isIconOnly && styles.iconOnly,
     buttonDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
@@ -693,11 +671,14 @@ export function Button({
       (variant === 'primary' || variant === 'destructive') &&
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.onSolidHorizontal
-        : groupStyles.onSolidVertical),
-    // Standalone floating buttons only — a grouped button's elevation is owned
+        : groupStyles.onSolidVertical), // Standalone floating buttons only — a grouped button's elevation is owned
     // by the ButtonGroup so the shared surface lifts as one unit.
     !buttonGroup && elevationStyles[elevation],
     width != null && dynamicStyles.width(width),
+    // AFTER the shared focus outline: the outline supplies width/style/offset
+    // for every variant, and `destructive` re-colors just the ring to match
+    // its own surface. Ordering is the mechanism — StyleX is last-wins.
+    variants[variant],
     xstyle,
   );
 

package/src/Calendar/Calendar.tsx

@@ -58,6 +58,7 @@ import {
   DATE_FORMAT_MONTH_YEAR,
 } from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -1102,7 +1103,7 @@ function DayCell({
             // the default rendering.
             marker: markerState,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             dayCellStyles.day,
             dayCellTheme.day,
             isOutside && dayCellStyles.dayOutside,

package/src/Calendar/styles.ts

@@ -258,14 +258,6 @@ export const dayCellTheme = stylex.create({
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
 
   // Outside days (adjacent months)

package/src/Carousel/Carousel.doc.mjs

@@ -66,8 +66,10 @@ export const docsZh = {
       'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表，或任何希望无需占据整页即可浏览的项目集合。',
     bestPractices: [
       {guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附，例如画廊或产品列表。'},
+      {guidance: true, description: '在小型可循环的集合（如照片画廊）上使用 hasLoop，此时从最后一项绕回第一项的滚动更自然。'},
       {guidance: true, description: '始终提供描述轮播内容的 aria-label，例如"精选产品"或"团队成员"。'},
       {guidance: true, description: '使用一致的间距和项目宽度，让轮播看起来是有意为之，而不是内容意外溢出。'},
+      {guidance: true, description: '信任内置导航：触控板用户可水平滑动，鼠标用户可按住 Shift 滚动滚轮来浏览项目。'},
       {guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动，关键内容应放在首屏。'},
       {guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
       {guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
@@ -94,6 +96,7 @@ export const docsDense = {
       'Carousel scrolls items horizontally when they overflow. Use for card grids, galleries, product lists.',
     bestPractices: [
       {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
+      {guidance: true, description: 'Reach for hasLoop on small cyclable sets (photo gallery) where wrapping past the last item back to the first feels natural.'},
       {guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
       {guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
       {guidance: true, description: 'Trust built-in navigation: trackpad users swipe horizontally, mouse users hold Shift + wheel to move through items.'},

package/src/Carousel/Carousel.tsx

@@ -560,9 +560,11 @@ export function Carousel({
               )}>
               <Button
                 icon={
-                  <span {...stylex.props(rtlStyles.mirror)}>
-                    <Icon icon="chevronLeft" size="xsm" />
-                  </span>
+                  <Icon
+                    icon="chevronLeft"
+                    size="xsm"
+                    xstyle={rtlStyles.mirror}
+                  />
                 }
                 label={t('@astryx.carousel.scrollLeft')}
                 variant="ghost"
@@ -585,9 +587,11 @@ export function Carousel({
               )}>
               <Button
                 icon={
-                  <span {...stylex.props(rtlStyles.mirror)}>
-                    <Icon icon="chevronRight" size="xsm" />
-                  </span>
+                  <Icon
+                    icon="chevronRight"
+                    size="xsm"
+                    xstyle={rtlStyles.mirror}
+                  />
                 }
                 label={t('@astryx.carousel.scrollRight')}
                 variant="ghost"

package/src/Chat/Chat.doc.mjs

@@ -26,6 +26,8 @@ export const docs = {
       {className: 'astryx-chat-system-message', visualProps: ['variant']},
       {className: 'astryx-chat-message-metadata'},
       {className: 'astryx-chat-send-button'},
+      {className: 'astryx-chat-dictation-button'},
+      {className: 'astryx-chat-layout-scroll-button'},
       {className: 'astryx-chat-tokenized-text'},
       {className: 'astryx-chat-tool-calls'},
       {className: 'astryx-trigger-menu'},

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 {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
 // =============================================================================
@@ -140,7 +141,12 @@ export function ChatDictationButton({
   return (
     <span
       ref={ref}
-      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
+      {...mergeProps(
+        themeProps('chat-dictation-button'),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}
       {...rest}>
       {isListening && (
         <span

package/src/Chat/ChatLayoutScrollButton.test.tsx

@@ -16,6 +16,28 @@ describe('ChatLayoutScrollButton', () => {
     expect(screen.getByTestId('scroll')).toBeTruthy();
   });
 
+  it('renders icon-only (no visible label text) in the default, label-less state', () => {
+    render(<ChatLayoutScrollButton isVisible onClick={() => {}} />);
+    const button = screen.getByRole('button', {name: 'Scroll to bottom'});
+    // The translated name must stay accessible-only. Button renders visible
+    // text whenever isIconOnly is false (its default), so a missing
+    // isIconOnly here previously rendered the full translation as clipped
+    // visible text inside the circular button instead of just the chevron.
+    expect(button.textContent).toBe('');
+  });
+
+  it('renders the label as visible text when provided', () => {
+    render(
+      <ChatLayoutScrollButton
+        isVisible
+        onClick={() => {}}
+        label="New messages"
+      />,
+    );
+    const button = screen.getByRole('button', {name: 'New messages'});
+    expect(button).toHaveTextContent('New messages');
+  });
+
   it('forwards rest props (data-*, aria-*, id) to the root element', () => {
     render(
       <ChatLayoutScrollButton

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -30,6 +30,7 @@ import {Icon} from '../Icon';
 import {Button} from '../Button';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
 // =============================================================================
@@ -128,7 +129,12 @@ export function ChatLayoutScrollButton({
   return (
     <div
       ref={ref}
-      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
+      {...mergeProps(
+        themeProps('chat-layout-scroll-button'),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}
       {...rest}>
       <div
         {...stylex.props(
@@ -144,6 +150,7 @@ export function ChatLayoutScrollButton({
           icon={<Icon icon="chevronDown" size="md" />}
           variant="ghost"
           size="md"
+          isIconOnly={!label}
           onClick={onClick}
           xstyle={[styles.button, label ? styles.buttonWithLabel : null]}>
           {label ?? undefined}