@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Field/InputClearButton.test.tsx

@@ -8,8 +8,8 @@
  * @output Unit tests for the shared clear-button primitive
  * @position Testing; validates InputClearButton.tsx — the single home for the
  *   clearable input family's clear (✕) affordance and its theme target. Covers
- *   the accessible name, the click callback, the decorative registry glyph,
- *   both theme targets, the touch hit area, and xstyle forwarding.
+ *   the accessible name, contextual hover tooltip, click callback, decorative
+ *   registry glyph, both theme targets, touch hit area, and xstyle forwarding.
  *
  * SYNC: When InputClearButton.tsx changes, update tests to match new behavior.
  */
@@ -17,7 +17,7 @@
 import {readFileSync} from 'node:fs';
 import path from 'node:path';
 import {describe, it, expect, vi, afterEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {
   InputClearButton,
@@ -95,6 +95,20 @@ describe('InputClearButton public props', () => {
 });
 
 describe('InputClearButton', () => {
+  it('uses the contextual label for the tooltip and accessible name', async () => {
+    const showPopover = vi.spyOn(HTMLElement.prototype, 'showPopover');
+    render(<InputClearButton label="Clear Search" onClick={() => {}} />);
+
+    const button = screen.getByRole('button', {name: 'Clear Search'});
+    const tooltip = screen.getByRole('tooltip', {hidden: true});
+    expect(tooltip).toHaveTextContent(/^Clear Search$/);
+    expect(button.getAttribute('aria-describedby')).toBe(tooltip.id);
+
+    fireEvent.mouseEnter(button);
+    await waitFor(() => expect(showPopover).toHaveBeenCalled());
+    showPopover.mockRestore();
+  });
+
   it('renders a real button with the given accessible label', () => {
     render(<InputClearButton label="Clear" onClick={() => {}} />);
     const button = screen.getByRole('button', {name: 'Clear'});

package/src/Field/InputClearButton.tsx

@@ -4,8 +4,9 @@
 
 /**
  * @file InputClearButton.tsx
- * @input Uses React, Button, Icon
- * @output Exports the public InputClearButton and an internal popup-aware variant.
+ * @input Uses React, Button, and Icon
+ * @output Exports the public InputClearButton and an internal popup-aware variant,
+ *   both with a contextual tooltip matching their required label.
  * @position Shared primitive. Every input that renders a clear affordance —
  *   TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
  *   DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
@@ -66,6 +67,7 @@ const styles = stylex.create({
 });
 
 export interface InputClearButtonProps {
+  /** Contextual accessible name for the button, such as "Clear Search". */
   label: string;
   onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
   xstyle?: stylex.StyleXStyles;
@@ -104,6 +106,7 @@ function renderInputClearButton({
       variant="ghost"
       size="sm"
       label={label}
+      tooltip={label}
       className={buttonTargetClassName}
       icon={
         <Icon

package/src/Field/PanelSearchInput.tsx

@@ -119,10 +119,13 @@ const styles = stylex.create({
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
     // Matches the option rows below it, so the query reads as the first line of
-    // the list. The coarse-pointer floor keeps iOS from zooming on focus.
+    // the list. The floor keeps iOS from zooming on focus — keyed to iOS
+    // alone, since only iOS WebKit implements -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     // The field draws the focus ring (see `field`), so the bare input must not

package/src/FieldStatus/__tests__/StatusMessage.a11y.states.ts

@@ -256,7 +256,7 @@ export const CORE_STATUS_MESSAGE_BINDING_STATES = [
       minValue: 0,
       maxValue: 100,
     },
-    focusSelector: '[role="progressbar"] [tabindex="0"]',
+    focusSelector: '[tabindex="0"]',
     storyId: 'a11y-status-message-pattern--progress-mark-focused-update',
   },
 ] as const satisfies ReadonlyArray<CoreStatusMessageBindingDefinition>;

package/src/FileInput/FileInput.tsx

@@ -231,9 +231,14 @@ const styles = stylex.create({
   },
   placeholderText: {
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-secondary'],
@@ -242,9 +247,13 @@ const styles = stylex.create({
   },
   fileNameText: {
     fontFamily: typographyVars['--font-family-body'],
+    // ...and the filename beside it keeps the same floor, so both lines the
+    // control shows stay the same size.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/Icon/Icon.doc.mjs

@@ -49,8 +49,9 @@ export const docs = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description: 'Icon size.',
-      default: "'md'",
+      description:
+        'Icon size. An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.',
+      default: "Contextual; otherwise 'md'",
     },
     {
       name: 'label',
@@ -153,8 +154,9 @@ export const docsZh = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
-      description: '图标尺寸。',
-      default: "'md'",
+      description:
+        '图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。',
+      default: "上下文默认值；否则为 'md'",
     },
     {
       name: 'label',
@@ -294,7 +296,7 @@ export const docsDense = {
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
-    size: 'Icon size.',
+    size: "explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     label:
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle:

package/src/Icon/Icon.spec.md

@@ -10,12 +10,18 @@ approved_by: cixzhang
 approved_at: 2026-08-30
 owners: [cixzhang, imdreamrunner]
 review_triggers: [public-api, behavior, theming, accessibility]
-verified_by: [packages/core/src/Icon/Icon.test.tsx, scripts/check-knowledge.mjs]
+verified_by:
+  [
+    packages/core/src/Icon/Icon.test.tsx,
+    packages/core/src/IconButton/IconButton.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
 modules: []
 families: []
 design_specs: []
 architecture:
   [
+    architecture:component-size-cascade,
     architecture:component-theming-surface,
     architecture:icon-resolution-and-component-slots,
     architecture:public-component-api,
@@ -33,11 +39,12 @@ semantics. Consumer usage remains documented in `Icon.doc.mjs`.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling, and
-  public API remain unchanged
+- Released default preserved: `yes` for explicit sizes and standalone Icons
+- Compatibility class: component-owned Icon slots may supply a contextual default;
+  explicit Icon sizes and the standalone `md` fallback remain unchanged
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: none; this record characterizes the released component
+- Migration decision: no consumer migration; omit `size` when the owning Astryx
+  component should select the contextual default
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -46,6 +53,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - Accepting a semantic icon key or a supplied icon component as the glyph source.
+- Resolving explicit, component-owned contextual, and standalone size defaults.
 - Applying Icon's size, color, theming target, and accessibility semantics to
   the rendered glyph.
 
@@ -53,19 +61,22 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The shared registry's key-resolution and fallback order — owned by the shared
   icon system.
+- Which contextual default an owning Astryx component selects for its icon slot —
+  owned by that component or family contract.
 - The meaning of a glyph in product context or whether nearby text makes it
   decorative — owned by the product callsite.
 - Interaction, focus, or control naming — owned by the interactive parent.
 - The artwork supplied by a consumer or registered through a theme.
+- A public Icon size-provider API; contextual transport is implementation detail.
 
 ## Public concepts
 
-| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default    | Owner            | Stability | Invalid-value behavior                                 |
-| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ---------- | ---------------- | --------- | ------------------------------------------------------ |
-| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required   | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
-| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | `md`       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`  | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
+| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default                                         | Owner            | Stability | Invalid-value behavior                                 |
+| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ |
+| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
+| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
 
 A namespaced key that does not resolve currently renders nothing. This is
 existing behavior, not an intentional fallback promise.
@@ -75,42 +86,51 @@ existing behavior, not an intentional fallback promise.
 Requirements identify their basis so observed code is not mistaken for an
 intentional decision.
 
-| ID  | Candidate invariant                                                                                                                                                                               | Basis                                      | Draft review state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------- |
-| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.      | Settled intent.                                         |
-| FR2 | Every rendered glyph MUST carry the `icon` theming target with its selected size and color reflected as target data.                                                                              | Current source, docs, and theming tests.   | Settled intent.                                         |
-| FR3 | Icon MUST apply the selected size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests. | Settled intent.                                         |
-| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.       | Current compatibility behavior; verify before changing. |
+| ID  | Candidate invariant                                                                                                                                                                               | Basis                                                 | Draft review state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.                 | Settled intent.                                         |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                     | Current source, docs, and theming tests.              | Settled intent.                                         |
+| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests.            | Settled intent.                                         |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
+| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent.                                         |
 
 ### Allowed variation
 
 - **AV1 — Artwork.** The path, view box, and internal structure may vary by icon
   source or theme without changing Icon's one-part consumer anatomy.
-- **AV2 — Rendering strategy.** Icon may render a supplied component directly or
+- **AV2 — Rendering strategy.** Icon may render a supplied icon component directly or
   use an internal wrapper for a resolved key; neither element shape is public
   anatomy.
 - **AV3 — Theme and consumer styling.** Existing theme and styling escape hatches
   may change visual CSS properties without changing glyph ownership.
+- **AV4 — Contextual mapping.** An owning Astryx component may map its own public
+  size or variant to an Icon default. That mapping belongs to the owner and MUST
+  preserve explicit Icon sizes and the standalone fallback.
 
 ### Representative states
 
-| State                     | Required invariant                                    | Allowed variation                              |
-| ------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
-| Semantic key              | One resolved glyph carries the `icon` target.         | Theme, registry, or built-in artwork.          |
-| Namespaced extension key  | A resolved extension glyph carries the `icon` target. | Consumer- or library-owned artwork.            |
-| Supplied icon component   | The supplied glyph carries the `icon` target.         | Component implementation and SVG internals.    |
-| Unresolved namespaced key | No glyph is currently rendered.                       | No fallback behavior is established by intent. |
+| State                            | Required invariant                                       | Allowed variation                              |
+| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
+| Semantic key                     | One resolved glyph carries the `icon` target.            | Theme, registry, or built-in artwork.          |
+| Namespaced extension key         | A resolved extension glyph carries the `icon` target.    | Consumer- or library-owned artwork.            |
+| Supplied icon component          | The supplied glyph carries the `icon` target.            | Component implementation and SVG internals.    |
+| Standalone Icon without `size`   | The resolved size is `md`.                               | Glyph source and color.                        |
+| Owned icon slot without `size`   | The nearest documented component default is used.        | The owning component's declared size mapping.  |
+| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size.                       |
+| Unresolved namespaced key        | No glyph is currently rendered.                          | No fallback behavior is established by intent. |
 
 ### Transformation and precedence order
 
-- **ORD1 — Presentation.** Apply the target, component size and color styles,
-  then merge consumer `xstyle`, `className`, inline `style`, and supported
+- **ORD1 — Size resolution.** Resolve explicit Icon `size` → nearest
+  component-owned contextual default → standalone `md` fallback.
+- **ORD2 — Presentation.** Apply the target, resolved size, and component color
+  styles, then merge consumer `xstyle`, `className`, inline `style`, and supported
   pass-through props in their established order.
 
 ### Performance and resources
 
 - **PR1 — Render work.** Icon owns no listeners, observers, or layout
-  measurement; semantic resolution is synchronous during render.
+  measurement; semantic and size resolution are synchronous during render.
 
 ## Accessibility contract
 
@@ -123,9 +143,9 @@ intentional decision.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                  | Representation authority                                      | Hierarchy role    | Component contract |
-| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | ------------------ |
-| Glyph            | Carries the selected visual symbol at the requested size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3      |
+| Anatomy or state | Design requirement                                                 | Representation authority                                      | Hierarchy role    | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- | ----------------- | ------------------ |
+| Glyph            | Carries the resolved visual symbol at the resolved size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3, FR5 |
 
 `Glyph` is the single conceptual consumer part in both source modes. Current
 implementation may render a supplied icon component directly or place a
@@ -144,26 +164,32 @@ not promise a `span`, `svg`, or other element type.
 
 ## Family and system relationships
 
+- `architecture:component-size-cascade` owns the shared explicit → nearest
+  provider → component fallback pattern and requires provider ownership to be
+  declared. Icon retains its own `xsm | sm | md | lg` axis outside the standard
+  element-size cascade and adopts that precedence for component-owned defaults.
 - `architecture:component-theming-surface` owns the qualification and validation
   rules for the `icon` target.
 - `architecture:icon-resolution-and-component-slots` owns semantic-key and
   component-slot resolution before Icon renders the selected source.
 - `architecture:public-component-api` owns admission and compatibility rules for
-  Icon's public props.
+  Icon's public props and observable defaults.
+- The owning component or family specifies each contextual Icon-size mapping.
+  The Button family currently maps `sm` and `md` controls to `sm` Icons and `lg`
+  controls to `md` Icons.
 - Icon has no current family contract.
 
 ## Verification map
 
-| Contract            | Verification                                                 | Representative states                         | Mutation or failure expectation                                                                                                                            | Audit section              |
-| ------------------- | ------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3            | `Icon.test.tsx` source-mode and sizing suites                | Built-in, themed, namespaced, component       | Breaking source rendering or cross-mode sizing fails assertions.                                                                                           | `audit:Icon/behavior`      |
-| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants    | Removing the target or breaking override composition fails existing assertions; `data-size` and `data-color` reflection currently lack focused assertions. | `audit:Icon/theming`       |
-| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                       | Decorative, labelled, explicit ARIA override  | Changing default or labelled semantics fails accessibility assertions.                                                                                     | `audit:Icon/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                    | `audit:Icon/theming`       |
+| Contract            | Verification                                                                   | Representative states                                           | Mutation or failure expectation                                                                                                             | Audit section              |
+| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.             | `audit:Icon/behavior`      |
+| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                      | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming`       |
+| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                    | Changing default or labelled semantics fails accessibility assertions.                                                                      | `audit:Icon/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                   | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                     | `audit:Icon/theming`       |
 
-Focused coverage for `data-size` and `data-color` on both glyph source modes is
-a checkable test gap; source inspection is the current evidence for that part of
-FR2.
+Focused coverage for `data-color` on both glyph source modes is a checkable test
+gap; source inspection is the current evidence for that part of FR2.
 
 ## Decision log
 
@@ -182,6 +208,21 @@ a `span`, `svg`, or other element.
 Rejected: separate wrapper and SVG anatomy entries, because those describe
 implementation strategies rather than stable consumer concepts.
 
+### DEC-2 — Owning components may provide contextual Icon defaults
+
+**Reference:** `component:Icon/DEC-2`
+**Decider:** cixzhang, 2026-09-23
+
+A person should see an icon that is proportionate to the Astryx component that
+owns its slot without every caller repeating a size. The owning component may
+therefore provide the default while an explicit Icon size remains authoritative
+and a standalone Icon remains `md`. Provider objects, hooks, and context shape
+remain private implementation details rather than public API.
+
+Rejected: an unconditional `md` default inside every composition, forcing every
+caller to repeat the owner-derived size, and exposing the provider mechanism as
+public API.
+
 ## Open questions
 
 None.

package/src/Icon/Icon.test.tsx

@@ -162,10 +162,13 @@ describe('Icon', () => {
     expect(icon).toHaveAttribute('aria-label', 'Home');
   });
 
-  it('uses default color and size when not specified', () => {
+  it('uses default color and standalone size when not specified', () => {
     render(<Icon icon={TestIcon} data-testid="icon" />);
-    // The component should render without errors with defaults
-    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    const icon = screen.getByTestId('icon');
+    expect(icon).toHaveAttribute('data-size', 'md');
+    expect(getComputedStyle(icon).width).toBe('1.25rem');
+    expect(getComputedStyle(icon).height).toBe('1.25rem');
   });
 
   it('applies aria-hidden by default in string (registry) mode', () => {

package/src/Icon/Icon.tsx

@@ -31,6 +31,14 @@ import {getIcon} from './globalIconRegistry';
 import type {IconName, NamespacedIconName} from './globalIconRegistry';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useIconSize} from './IconDefaultSizeContext';
+import {
+  iconBoxSizeStyles,
+  iconSizeStyles,
+  type IconSize,
+} from './IconSize.stylex';
+
+export type {IconSize} from './IconSize.stylex';
 
 // =============================================================================
 // Styles
@@ -110,75 +118,11 @@ const colorStyles = stylex.create({
   },
 });
 
-/**
- * Size styles for direct SVG icon components.
- * Uses width/height only — SVG components handle their own viewBox scaling.
- *
- * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
- * in step with text when the document font-size changes, matching the rest of
- * the design system's rem-based type scale. Values are the px-equivalents at a
- * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
- */
-const sizeStyles = stylex.create({
-  xsm: {
-    width: '0.75rem',
-    height: '0.75rem',
-  },
-  sm: {
-    width: '1rem',
-    height: '1rem',
-  },
-  md: {
-    width: '1.25rem',
-    height: '1.25rem',
-  },
-  lg: {
-    width: '1.5rem',
-    height: '1.5rem',
-  },
-});
-
-/**
- * Size styles for string-based (registry) icons.
- * Includes fontSize so that 1em-based icons from the registry scale correctly.
- *
- * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
- * root font-size instead of being locked to absolute pixels.
- */
-const spanSizeStyles = stylex.create({
-  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
-     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
-     the 14px-anchored textSizeVars type scale. Values are rem so icons track
-     the root font-size. */
-  xsm: {
-    width: '0.75rem',
-    height: '0.75rem',
-    fontSize: '0.75rem',
-  },
-  sm: {
-    width: '1rem',
-    height: '1rem',
-    fontSize: '1rem',
-  },
-  md: {
-    width: '1.25rem',
-    height: '1.25rem',
-    fontSize: '1.25rem',
-  },
-  lg: {
-    width: '1.5rem',
-    height: '1.5rem',
-    fontSize: '1.5rem',
-  },
-  /* eslint-enable @astryx/no-hardcoded-styles */
-});
-
 // =============================================================================
 // Types
 // =============================================================================
 
 export type IconColor = keyof typeof colorStyles;
-export type IconSize = keyof typeof sizeStyles;
 
 /**
  * Type for icon components that can be passed to Icon.
@@ -215,7 +159,9 @@ export interface IconProps extends Omit<
    * - 'sm': 1rem (16px at a 16px root)
    * - 'md': 1.25rem (20px at a 16px root)
    * - 'lg': 1.5rem (24px at a 16px root)
-   * @default 'md'
+   *
+   * An explicit value wins. When omitted, Icon uses the nearest default supplied
+   * by an owning Astryx component for its icon slot, then falls back to 'md'.
    */
   size?: IconSize;
   /**
@@ -297,7 +243,7 @@ function getIconA11yProps(
 export function Icon({
   icon,
   color = 'inherit',
-  size = 'md',
+  size: sizeProp,
   label,
   ref,
   className,
@@ -305,6 +251,7 @@ export function Icon({
   xstyle,
   ...props
 }: IconProps) {
+  const size = useIconSize(sizeProp);
   // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
   // meaningful image (role="img" + aria-label) when `label` is non-empty.
   const a11yProps = getIconA11yProps(label);
@@ -341,7 +288,12 @@ export function Icon({
       // precedence as escape hatches.
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.root, colorStyles[color], sizeStyles[size], xstyle),
+        stylex.props(
+          styles.root,
+          colorStyles[color],
+          iconSizeStyles[size],
+          xstyle,
+        ),
         className ?? undefined,
         style,
       )}
@@ -410,7 +362,7 @@ function IconFromRegistry({
         stylex.props(
           styles.span,
           colorStyles[color],
-          spanSizeStyles[size],
+          iconBoxSizeStyles[size],
           xstyle,
         ),
         className ?? undefined,

package/src/Icon/IconDefaultSizeContext.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file IconDefaultSizeContext.ts
+ * @input Uses React context and an optional Icon size prop
+ * @output Supplies a component-owned default size to descendant Icon instances
+ * @position Internal Icon sizing context; consumed by Icon and icon-slot owners
+ */
+
+import {createContext, use} from 'react';
+import type {IconSize} from './IconSize.stylex';
+
+const IconDefaultSizeContext = createContext<IconSize | null>(null);
+IconDefaultSizeContext.displayName = 'IconDefaultSizeContext';
+
+export const IconDefaultSizeProvider = IconDefaultSizeContext.Provider;
+
+export function useIconSize(size: IconSize | undefined): IconSize {
+  const contextualSize = use(IconDefaultSizeContext);
+  return size ?? contextualSize ?? 'md';
+}

package/src/Icon/IconSize.stylex.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file IconSize.stylex.ts
+ * @input Defines the Icon size scale
+ * @output Exports shared Icon size types and StyleX styles
+ * @position Internal Icon sizing source; consumed by Icon and icon-slot owners
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Icon sizes are expressed in `rem` so they scale with the root font-size.
+ * Values are the px-equivalents at a 16px root: 12, 16, 20, and 24px.
+ */
+const iconSizeValues = {
+  xsm: '0.75rem',
+  sm: '1rem',
+  md: '1.25rem',
+  lg: '1.5rem',
+} as const;
+
+export type IconSize = keyof typeof iconSizeValues;
+
+/** Size styles for direct SVG icon components. */
+export const iconSizeStyles = stylex.create({
+  xsm: {
+    width: iconSizeValues.xsm,
+    height: iconSizeValues.xsm,
+  },
+  sm: {
+    width: iconSizeValues.sm,
+    height: iconSizeValues.sm,
+  },
+  md: {
+    width: iconSizeValues.md,
+    height: iconSizeValues.md,
+  },
+  lg: {
+    width: iconSizeValues.lg,
+    height: iconSizeValues.lg,
+  },
+});
+
+/**
+ * Size styles for icon boxes and string-based registry icons. `fontSize`
+ * keeps 1em-based icons in step with the box.
+ */
+export const iconBoxSizeStyles = stylex.create({
+  xsm: {
+    width: iconSizeValues.xsm,
+    height: iconSizeValues.xsm,
+    fontSize: iconSizeValues.xsm,
+  },
+  sm: {
+    width: iconSizeValues.sm,
+    height: iconSizeValues.sm,
+    fontSize: iconSizeValues.sm,
+  },
+  md: {
+    width: iconSizeValues.md,
+    height: iconSizeValues.md,
+    fontSize: iconSizeValues.md,
+  },
+  lg: {
+    width: iconSizeValues.lg,
+    height: iconSizeValues.lg,
+    fontSize: iconSizeValues.lg,
+  },
+});