@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file BottomSheetPanel.test.tsx
  * @input Uses vitest, Testing Library, BottomSheetPanel
- * @output Tests the shared sheet surface motion contract
+ * @output Tests the shared sheet surface motion and keyboard scroll contracts
  * @position Internal presentation tests shared by standalone and switcher modes
  */
 
@@ -50,6 +50,7 @@ function renderPanel(
 ) {
   return render(
     <BottomSheetPanel
+      label="Sheet details"
       state={state}
       height="hug"
       style={panelTransitionStyle}
@@ -92,6 +93,7 @@ describe('BottomSheetPanel', () => {
     const onMotionComplete = vi.fn();
     const {rerender} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'retained', motion: 'covered', alignmentOffset: 0}}
         height="hug"
         style={panelTransitionStyle}
@@ -104,6 +106,7 @@ describe('BottomSheetPanel', () => {
 
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: true}}
         height="hug"
         style={panelTransitionStyle}
@@ -139,6 +142,7 @@ describe('BottomSheetPanel', () => {
 
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'exiting'}}
         height="hug"
         style={panelTransitionStyle}
@@ -166,6 +170,7 @@ describe('BottomSheetPanel', () => {
     const onMotionComplete = vi.fn();
     render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: true}}
         height="hug"
         onDismiss={() => {}}
@@ -184,6 +189,7 @@ describe('BottomSheetPanel', () => {
       const onMotionComplete = vi.fn();
       render(
         <BottomSheetPanel
+          label="Sheet details"
           state={{kind: 'open', entering: true}}
           height="hug"
           style={{
@@ -211,6 +217,7 @@ describe('BottomSheetPanel', () => {
     const panelRef = vi.fn();
     const {rerender, unmount} = render(
       <BottomSheetPanel
+        label="Sheet details"
         ref={panelRef}
         state={{kind: 'open', entering: false}}
         height="hug"
@@ -223,6 +230,7 @@ describe('BottomSheetPanel', () => {
     expect(panelRef).toHaveBeenCalledTimes(1);
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         ref={panelRef}
         state={{kind: 'open', entering: false}}
         height="hug"
@@ -361,6 +369,7 @@ describe('BottomSheetPanel', () => {
 
     const {container: closing} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'exiting'}}
         height="hug"
         onDismiss={() => {}}
@@ -379,6 +388,7 @@ describe('BottomSheetPanel', () => {
 
     const {container: resting} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: false}}
         height="hug"
         onDismiss={() => {}}

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -4,14 +4,14 @@
 
 /**
  * @file BottomSheetPanel.tsx
- * @input Uses React, StyleX, theme tokens, useSheetGestures
- * @output Internal BottomSheetPanel surface and motion-state types
+ * @input Uses React, StyleX, theme tokens, sheet gestures, shared scroll behavior, and the host label
+ * @output Internal BottomSheetPanel with a keyboard-reachable scrolling body and motion-state types
  * @position Shared presentation layer for standalone and switcher BottomSheets
  *
  * This component owns everything intrinsic to a sheet surface: height budgets,
  * drag and snap gestures, the handle and scrolling body, motion styles, and
- * transition completion. It deliberately does not own a dialog, focus, inert
- * state, or switcher registration; those belong to the hosting controller.
+ * transition completion. It owns the body's keyboard access; dialog focus
+ * entry/return, inert state, and switcher registration belong to the host.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
@@ -33,17 +33,20 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {useDevWarning} from '../hooks';
+import {useScrollableArea} from '../hooks/useScrollableArea';
 import {
   borderVars,
   colorVars,
   durationVars,
   easeVars,
+  focusVars,
   radiusVars,
   shadowVars,
   sizeVars,
   spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps, themeProps} from '../utils';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {
   isValidSnapPoint,
@@ -211,9 +214,11 @@ const styles = stylex.create({
     flexGrow: 1,
     minHeight: 0,
     boxSizing: 'border-box',
-    overflowY: 'auto',
-    overscrollBehavior: 'none',
     touchAction: 'pan-y',
+    outlineOffset: {
+      default: 0,
+      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
+    },
     // The scrolling area paints the surface itself, covering the sheet's whole
     // inner box. Without it the sheet's edge is not uniform: a theme that packs
     // an inset ring into --shadow-high (the bundled themes all add one in dark
@@ -229,6 +234,15 @@ const styles = stylex.create({
     // space a content wrapper's own top padding already provides.
     paddingBlockEnd: 0,
   },
+  content: {
+    // Preserve the body's block formatting (including margin/float isolation)
+    // and its definite percentage-height basis. min-content lets this real
+    // observed box grow with async content beyond a fixed-height viewport.
+    display: 'flow-root',
+    boxSizing: 'border-box',
+    height: '100%',
+    minHeight: 'min-content',
+  },
   tallKeyboardBody: {
     scrollPaddingBlockEnd: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
     '::after': {
@@ -265,6 +279,8 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   state: BottomSheetPanelState;
   height: BottomSheetHeight | number | string;
+  /** Existing host name, reused for the keyboard scrolling group. */
+  label: string;
   children: ReactNode;
   snapPoints?: ReadonlyArray<BottomSheetSnapPoint>;
   isSwipeDismissAllowed?: boolean;
@@ -391,6 +407,7 @@ export function BottomSheetPanel({
   ref,
   state,
   height,
+  label,
   children,
   snapPoints,
   className,
@@ -490,6 +507,17 @@ export function BottomSheetPanel({
     onScrimOpacity,
   });
 
+  const {getViewportProps, getContentProps} = useScrollableArea({
+    // The previous overflow-y:auto also computed overflow-x:auto. Keep wide
+    // content reachable instead of clipping that existing inline scroll path.
+    axis: 'both',
+    keyboardAccess: {owner: 'contentOrViewport', label},
+    overscroll: 'contain',
+    // The sheet body deliberately remains the boundary for sheet-local sticky
+    // content while fitting, as it was before shared scroll adoption.
+    stickyContainment: 'always',
+  });
+
   const setElement = useCallback(
     (element: HTMLDivElement | null) => {
       sheetRef(element);
@@ -656,17 +684,22 @@ export function BottomSheetPanel({
         <div {...stylex.props(styles.handlePill)} />
       </div>
       <div
-        {...mergeProps(
-          stylex.props(
-            styles.body,
-            height === 'tall' && styles.tallKeyboardBody,
+        {...getViewportProps<HTMLDivElement>({
+          ...bodyProps,
+          ...mergeProps(
+            stylex.props(
+              focusOutlineStyles.focusVisible,
+              styles.body,
+              height === 'tall' && styles.tallKeyboardBody,
+            ),
+            scrollPreservationInset > 0
+              ? {style: {paddingBlockEnd: `${scrollPreservationInset}px`}}
+              : {},
           ),
-          scrollPreservationInset > 0
-            ? {style: {paddingBlockEnd: `${scrollPreservationInset}px`}}
-            : {},
-        )}
-        {...bodyProps}>
-        {children}
+        })}>
+        <div {...getContentProps<HTMLDivElement>(stylex.props(styles.content))}>
+          {children}
+        </div>
       </div>
     </div>
   );

package/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts

@@ -0,0 +1,344 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetKeyboard.a11y.browser.spec.ts
+ * @input Built BottomSheet stories and real Chromium/WebKit keyboard input
+ * @output Browser evidence for shared focus delegation, traversal, and native scrolling
+ * @position Cross-browser proof for useScrollableArea's contentOrViewport policy
+ */
+
+import {expect, test, type Page, type Locator} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+// macOS WebKit defaults to text-field traversal. Option+Tab selects its native
+// all-controls traversal, equivalent to enabling Safari's keyboard preference.
+function tabKey(browserName: string, reverse = false): string {
+  return `${browserName === 'webkit' && process.platform === 'darwin' ? 'Alt+' : ''}${reverse ? 'Shift+' : ''}Tab`;
+}
+
+async function mount(page: Page, browserName: string, variant = 'button') {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-bottomsheet--keyboard-delegation&viewMode=story`,
+  );
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  await page.getByLabel('Content case').selectOption(variant);
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+  // WebKit includes the non-modal dialog host in sequential navigation;
+  // Chromium enters its descendants directly. Start immediately before the body.
+  const before =
+    browserName === 'webkit'
+      ? page.getByRole('dialog', {name: 'Keyboard reading', exact: true})
+      : page.getByRole('button', {name: 'Toggle modal', exact: true});
+  await before.focus();
+  return {viewport, before};
+}
+
+for (const variant of ['button', 'link']) {
+  test(`${variant}: forward entry delegates once and reverse traversal exits`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    const first = page.getByRole(variant === 'button' ? 'button' : 'link', {
+      name: variant === 'button' ? 'First action' : 'First link',
+      exact: true,
+    });
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await expect(first).toHaveAccessibleName(
+      variant === 'button' ? 'First action' : 'First link',
+    );
+    await page.keyboard.press(tabKey(browserName));
+    await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(first).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+  });
+}
+
+for (const variant of [
+  'text',
+  'input',
+  'disabled',
+  'nested',
+  'native-scroll',
+  'radiogroup',
+  'slider',
+  'combobox',
+  'listbox',
+  'menu',
+  'grid',
+  'tree',
+  'tablist',
+  'toolbar',
+]) {
+  test(`${variant}: retains a named viewport stop`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    await page.keyboard.press(tabKey(browserName));
+    await expect(viewport).toBeFocused();
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+  });
+}
+
+async function scrollRange(viewport: Locator) {
+  return viewport.evaluate(element => ({
+    position: element.scrollTop,
+    max: element.scrollHeight - element.clientHeight,
+  }));
+}
+
+for (const key of ['PageDown', 'ArrowDown']) {
+  test(`${key}: reaches both scroll edges after delegation`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport} = await mount(page, browserName);
+    await page.keyboard.press(tabKey(browserName));
+    const first = page.getByRole('button', {name: 'First action', exact: true});
+    await expect(first).toBeFocused();
+    for (let count = 0; count < 300; count++) {
+      const {position, max} = await scrollRange(viewport);
+      if (position >= max - 1) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: key === 'ArrowDown' ? 50 : 25});
+    }
+    await expect
+      .poll(async () => {
+        const {position, max} = await scrollRange(viewport);
+        // WebKit can overshoot a native edge while showing rubber-band feedback.
+        return max - position;
+      })
+      .toBeLessThanOrEqual(1);
+    for (let count = 0; count < 300; count++) {
+      if ((await scrollRange(viewport)).position <= 1) {
+        break;
+      }
+      await page.keyboard.press(key === 'PageDown' ? 'PageUp' : 'ArrowUp', {
+        delay: key === 'ArrowDown' ? 50 : 25,
+      });
+    }
+    await expect
+      .poll(async () => (await scrollRange(viewport)).position)
+      .toBeLessThanOrEqual(1);
+    await expect(first).toBeFocused();
+  });
+}
+
+test('pointer and programmatic focus stay on the viewport, including during keydown', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.focus();
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await viewport.click({position: {x: 4, y: 40}});
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await before.evaluate(element => {
+    element.addEventListener('keydown', event => {
+      if (event instanceof KeyboardEvent && event.key === 'Tab') {
+        event.preventDefault();
+        document
+          .querySelector<HTMLElement>(
+            '[role="group"][aria-label="Keyboard reading"]',
+          )
+          ?.focus();
+      }
+    });
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('dynamic eligibility is checked at the next entry without mutation observation', async ({
+  page,
+  browserName,
+}) => {
+  await page.addInitScript(() => {
+    const Original = window.MutationObserver;
+    const observers: MutationObserver[] = [];
+    window.MutationObserver = class extends Original {
+      constructor(callback: MutationCallback) {
+        super(callback);
+        observers.push(this);
+      }
+    };
+    Object.assign(window, {
+      stopMutationObservers: () =>
+        observers.forEach(observer => observer.disconnect()),
+    });
+  });
+  const {viewport, before} = await mount(page, browserName);
+  await page.evaluate(() => {
+    (
+      window as unknown as {stopMutationObservers: () => void}
+    ).stopMutationObservers();
+  });
+  await viewport.focus();
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await first.evaluate(element => element.setAttribute('disabled', ''));
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.removeAttribute('disabled'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    const input = document.createElement('input');
+    input.setAttribute('aria-label', 'Inserted input');
+    element.prepend(input);
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+  await page.getByLabel('Inserted input').evaluate(element => element.remove());
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.setAttribute('role', 'combobox'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('modal BottomSheet keeps native focus containment without cycling through the viewport', async ({
+  page,
+  browserName,
+}) => {
+  await mount(page, browserName);
+  await page.getByRole('button', {name: 'Toggle modal', exact: true}).click();
+  const dialog = page.getByRole('dialog', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect
+    .poll(async () => dialog.evaluate(element => element.matches(':modal')))
+    .toBe(true);
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  const panel = dialog.locator('.astryx-bottom-sheet');
+  await panel.focus();
+  await page.keyboard.press(tabKey(browserName));
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await expect(first).toBeFocused();
+  await page.keyboard.press(tabKey(browserName, true));
+  await expect(viewport).not.toBeFocused();
+  await expect(first).not.toBeFocused();
+  // Native dialog traversal may wrap to another sheet target or browser chrome;
+  // it must never focus the inert background or create a viewport/child loop.
+  await expect(
+    page.getByRole('button', {name: 'Before sheet', includeHidden: true}),
+  ).not.toBeFocused();
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+});
+
+test('fitting text removes the viewport stop while preserving current focus', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName, 'text');
+  await viewport.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    element.textContent = 'Short reading content';
+  });
+  await expect(viewport).not.toHaveAttribute('data-scrollable-block', 'true');
+  await expect(viewport).toHaveAttribute('tabindex', '-1');
+  await expect(viewport).toBeFocused();
+});
+
+test('horizontal overflow remains keyboard scrollable after delegation', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.evaluate(element => {
+    const content = element.querySelector<HTMLElement>('[data-scroll-content]');
+    if (content != null) {
+      content.style.width = `${element.clientWidth + 320}px`;
+    }
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(
+    page.getByRole('button', {name: 'First action', exact: true}),
+  ).toBeFocused();
+  for (const key of ['ArrowRight', 'ArrowLeft']) {
+    for (let count = 0; count < 100; count++) {
+      const atEdge = await viewport.evaluate(
+        (element, forward) =>
+          forward
+            ? element.scrollLeft >=
+              element.scrollWidth - element.clientWidth - 1
+            : element.scrollLeft <= 1,
+        key === 'ArrowRight',
+      );
+      if (atEdge) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: 50});
+    }
+    await expect
+      .poll(async () =>
+        viewport.evaluate(
+          (element, forward) =>
+            forward
+              ? element.scrollWidth - element.clientWidth - element.scrollLeft
+              : element.scrollLeft,
+          key === 'ArrowRight',
+        ),
+      )
+      .toBeLessThanOrEqual(1);
+  }
+});
+
+test('does not skip an aria-hidden first tab stop to delegate to a later action', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName);
+  await page
+    .getByRole('button', {name: 'First action', exact: true})
+    .evaluate(element => {
+      element.setAttribute('aria-hidden', 'true');
+    });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});

package/src/Button/Button.doc.mjs

@@ -157,8 +157,8 @@ export const docs = {
       name: 'icon',
       type: 'ReactNode',
       description:
-        'Icon element rendered before the label text.',
-      slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+        'Icon element rendered before the label text. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
+      slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
     },
     {
       name: 'isIconOnly',
@@ -210,7 +210,7 @@ export const docs = {
       name: 'href',
       type: 'string',
       description:
-        'When provided, renders the button as a link element (<a> or custom link component).',
+        'When provided, renders the button as a link element (<a> or custom link component). The destination follows the shared navigation rule described on the Link `href` prop.',
     },
     {
       name: 'as',
@@ -294,7 +294,7 @@ export const docsZh = {
       description: '禁用按钮。存在工具提示时，使用 aria-disabled 代替原生 disabled 以保持可聚焦。',
       default: 'false',
     },
-    {name: 'icon', type: 'ReactNode', description: '图标元素。仅提供 icon 而不提供 children 时，按钮渲染为正方形的纯图标按钮。'},
+    {name: 'icon', type: 'ReactNode', description: '图标元素。未显式指定尺寸的 Astryx Icon 在 sm/md 按钮中默认为 sm，在 lg 按钮中默认为 md。仅提供 icon 而不提供 children 时，按钮渲染为正方形的纯图标按钮。'},
     {name: 'width', type: 'SizeValue', description: "按钮宽度。数字按像素处理，字符串按原样使用（如 '100%' 表示全宽按钮）。默认按内容自适应宽度。"},
     {name: 'children', type: 'ReactNode', description: '可选的可见内容覆盖；label 仍然是必需的（用于无障碍名称）。大多数情况使用 <Button label="Save" />。'},
     {
@@ -361,7 +361,7 @@ export const docsDense = {
     value: 'HTML value for form submission',
     form: 'associates button with form element by ID',
     isLoading: 'shows spinner+disables interaction; announces via live region',
-    icon: 'icon element rendered before label text',
+    icon: 'icon element rendered before label text; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
     width: "Width of button. Numbers=pixels, strings=as-is (e.g. '100%' for full-width).",
     children: 'optional visible override; label is still required for a11y. Prefer <Button label="Save" /> over using children',

package/src/Button/Button.tsx

@@ -38,6 +38,8 @@ import {
 } from '../theme/tokens.stylex';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
+import {IconDefaultSizeProvider} from '../Icon/IconDefaultSizeContext';
+import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
@@ -170,17 +172,6 @@ const sizeStyles = stylex.create({
   },
 });
 
-/**
- * Icon size per button size.
- * Matches Icon sizing: sm/md=16px, lg=20px.
- * fontSize is set so emoji and text-based icons scale correctly.
- */
-const iconSizeStyles = stylex.create({
-  sm: {width: 16, height: 16, fontSize: 16},
-  md: {width: 16, height: 16, fontSize: 16},
-  lg: {width: 20, height: 20, fontSize: 20},
-});
-
 /**
  * Resting elevation for floating buttons (e.g. a FAB). `none` is the default
  * flat button; `low`/`med`/`high` map to the shadow token scale. 'none' stays
@@ -233,6 +224,12 @@ export type ButtonVariant = keyof ButtonVariantMap;
  */
 export type ButtonSize = keyof typeof sizeStyles;
 
+const iconSizeByButtonSize = {
+  sm: 'sm',
+  md: 'sm',
+  lg: 'md',
+} satisfies Record<ButtonSize, IconSize>;
+
 export interface ButtonProps extends BaseProps<HTMLButtonElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLButtonElement>;
@@ -683,6 +680,8 @@ export function Button({
     style,
   );
 
+  const iconSize = iconSizeByButtonSize[size];
+
   const buttonContent = (
     <>
       {isLoadingState && (
@@ -705,8 +704,11 @@ export function Button({
         )}
         aria-hidden={isLoadingState || undefined}>
         {icon && (
-          <span {...stylex.props(styles.iconWrapper, iconSizeStyles[size])}>
-            {icon}
+          <span
+            {...stylex.props(styles.iconWrapper, iconBoxSizeStyles[iconSize])}>
+            <IconDefaultSizeProvider value={iconSize}>
+              {icon}
+            </IconDefaultSizeProvider>
           </span>
         )}
         {isIconOnly ? null : (