@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

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,
+  },
+});

package/src/IconButton/IconButton.doc.mjs

@@ -20,9 +20,9 @@ export const docs = {
     {
       name: 'icon',
       type: 'ReactNode',
-      description: 'Icon element rendered inside the button.',
+      description: 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
       required: true,
-      slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+      slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
     },
     {
       name: 'variant',
@@ -137,7 +137,7 @@ export const docsDense = {
   },
   propDescriptions: {
     label: 'accessible label; used as aria-label, not rendered as visible text',
-    icon: 'icon element rendered inside button',
+    icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     variant: 'visual style variant',
     size: 'size variant',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',

package/src/IconButton/IconButton.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {Icon} from '../Icon/Icon';
 import {IconButton} from './IconButton';
 
 describe('IconButton', () => {
@@ -52,6 +53,45 @@ describe('IconButton', () => {
     expect(screen.getByRole('button', {name: 'Add'})).toBeInTheDocument();
   });
 
+  it.each([
+    ['sm', 'sm', '1rem'],
+    ['md', 'sm', '1rem'],
+    ['lg', 'md', '1.25rem'],
+  ] as const)(
+    'renders the %s button wrapper and inherited Icon at the same size',
+    (buttonSize, iconSize, renderedSize) => {
+      render(
+        <IconButton
+          label="Add"
+          icon={<Icon icon="check" data-testid="icon" />}
+          size={buttonSize}
+        />,
+      );
+
+      const icon = screen.getByTestId('icon');
+      const wrapper = icon.parentElement;
+      expect(wrapper).not.toBeNull();
+
+      expect(icon).toHaveAttribute('data-size', iconSize);
+      expect(getComputedStyle(icon).width).toBe(renderedSize);
+      expect(getComputedStyle(icon).height).toBe(renderedSize);
+      expect(getComputedStyle(wrapper!).width).toBe(renderedSize);
+      expect(getComputedStyle(wrapper!).height).toBe(renderedSize);
+    },
+  );
+
+  it('preserves an explicit Astryx Icon size', () => {
+    render(
+      <IconButton
+        label="Add"
+        icon={<Icon icon="check" size="lg" data-testid="icon" />}
+        size="sm"
+      />,
+    );
+
+    expect(screen.getByTestId('icon')).toHaveAttribute('data-size', 'lg');
+  });
+
   it('handles click events', async () => {
     const user = userEvent.setup();
     const handleClick = vi.fn();

package/src/Item/Item.doc.mjs

@@ -22,6 +22,10 @@ export const docs = {
     vars: [
       {name: '--_item-label-color', description: 'Color of the label line. Unset by default (the label uses the primary text token); a parent sets it to recolor the label it renders, as the destructive dropdown/context menu item does.', default: 'var(--color-text-primary)', private: true},
       {name: '--_item-description-color', description: 'Companion to --_item-label-color for the secondary description line.', default: 'var(--color-text-secondary)', private: true},
+      {name: '--_item-inset-inline', description: 'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.', default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")', private: true},
+    ],
+    derived: [
+      {property: 'paddingInline', vars: ['--_item-inset-inline']},
     ],
   },
   components: [
@@ -43,7 +47,7 @@ export const docs = {
         {name: 'layout', type: "'stacked' | 'inline'", description: 'How the label and description sit together. stacked puts the description on its own line below the label; inline keeps both on one line, description ellipsizing first, so the row fits a fixed-height host.', default: "'stacked'"},
         {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
         {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set.'},
-        {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},
+        {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element. The destination follows the shared navigation rule described on the Link `href` prop.'},
         {name: 'target', type: "'_blank' | '_self'", description: 'Link target. Only used with href. target="_blank" automatically adds noopener noreferrer.'},
         {name: 'rel', type: 'string', description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".'},
         {name: 'isHighlighted', type: 'boolean', description: 'Highlighted state (hover/keyboard focus appearance).', default: 'false'},
@@ -167,7 +171,7 @@ export const docsDense = {
         onClick: 'Click handler; enables button semantics.',
         interactiveRef:
           'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
-        href: 'Link URL; enables anchor semantics.',
+        href: 'Link URL; enables anchor semantics. Follows the shared navigation rule (see Link href).',
         target:
           'Link target, only with href. target="_blank" auto-adds noopener noreferrer.',
         rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',

package/src/Item/Item.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Item.tsx
  * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
- * @output Exports Item component, ItemProps type
+ * @output Exports Item component, ItemProps type; publishes the shared inline inset
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -209,7 +209,13 @@ const styles = stylex.create({
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
-    paddingInline: spacingVars['--spacing-2'],
+    // The inline inset is published as --_item-inset-inline and the padding
+    // derives from it, so consumers that need to compensate for the inset
+    // (List's edgeCompensation) read the var instead of mirroring the values.
+    // Themes that set paddingInline on `item` also feed this var via the
+    // derived var registry, keeping padding and compensation in sync.
+    '--_item-inset-inline': spacingVars['--spacing-2'],
+    paddingInline: 'var(--_item-inset-inline)',
     position: 'relative',
     boxSizing: 'border-box',
     textAlign: 'start',
@@ -356,7 +362,7 @@ const densityStyles = stylex.create({
   },
   spacious: {
     paddingBlock: spacingVars['--spacing-3'],
-    paddingInline: spacingVars['--spacing-3'],
+    '--_item-inset-inline': spacingVars['--spacing-3'],
   },
 });
 

package/src/Kbd/Kbd.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       name: 'keys',
       type: 'string',
       description:
-        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape and return for enter.',
       required: true,
     },
     {
@@ -72,7 +72,7 @@ export const docsZh = {
       name: 'keys',
       type: 'string',
       description:
-        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right。',
+        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right、plus。别名：esc 等同于 escape，return 等同于 enter。',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape, return for enter.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
     className: 'CSS class for root element. Prefer xstyle; className for non-StyleX integration.',
     style: 'Inline styles for root element. Prefer xstyle; inline styles bypass StyleX optimization.',