An open source design system that's fully customizable and agent ready
TypeScript
fix(Button): inherit default icon size (#5762)
rubyycheungf22695aab91d
diff --git a/.changeset/button-icon-default-size.md b/.changeset/button-icon-default-size.mdnew file mode 100644index 0000000000..fa2237a201--- /dev/null+++ b/.changeset/button-icon-default-size.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+---++[fix] Size an Astryx Icon without an explicit size to match its Button or+IconButton: 16px for small and medium controls, and 20px for large controls.++@rubyycheungdiff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex a71d95c7e2..bfcec9a279 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -8,6 +8,17 @@"overlayRoot": ".astryx-app-shell"}},+ {+ "component": "Button",+ "storyId": "core-button--icon-with-text",+ "dims": [+ "D2"+ ],+ "selectors": {+ "prev": "[data-testid=\"button-leading-icon\"]",+ "next": "[data-testid=\"button-label\"]"+ }+ },{"component": "ButtonGroup","storyId": "core-buttongroup--horizontal",diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex df34ca05ce..656f1928f0 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -24,6 +24,10 @@"component": "core/Heading","reason": "Heading is typography-only. Its level, type, weight, color, wrapping, truncation, and decoration styles do not position or reorder content on the inline axis; justify uses logical start/end values, and the optional truncation tooltip uses logical placement vocabulary. It renders no directional glyph, separator, control, physical inset, transform, drag, scroll, overlay, or directional keyboard behavior."},+ {+ "component": "core/Icon",+ "reason": "Across the Core/Icon stories, Icon renders one centered, non-directional glyph and only owns its size, color, theme target, and accessibility presentation. It has no component-owned order, inline-side placement, scrolling, dragging, overlay, or keyboard behavior; when a caller chooses a directional glyph, that callsite owns the semantic direction and any required mirroring."+ },{"component": "core/Spinner","reason": "No direction-sensitive visual, layout, or behavior. The ring is a concentric SVG — two <circle> elements sharing one center, sized by diameter and stroke, with no physical inset, offset, or asymmetry to mirror. Its only layout is the optional label wrapper, which is flexDirection: column + alignItems: center, so the label stacks below the ring on both axes' terms rather than beside it. The rotation keyframe (0deg to 360deg) is deliberately absolute: a loading spinner turns the same way in every locale, and mirroring it would be a bug, not RTL support."diff --git a/apps/storybook/stories/Button.stories.tsx b/apps/storybook/stories/Button.stories.tsxindex 86d9fd32ef..9bd22871a8 100644--- a/apps/storybook/stories/Button.stories.tsx+++ b/apps/storybook/stories/Button.stories.tsx@@ -133,8 +133,14 @@ export const IconWithText: Story = {<Buttonlabel="Settings"variant="secondary"- icon={<Cog6ToothIcon style={{width: 16, height: 16}} />}- />+ icon={+ <Cog6ToothIcon+ data-testid="button-leading-icon"+ style={{width: 16, height: 16}}+ />+ }>+ <span data-testid="button-label">Settings</span>+ </Button><Buttonlabel="Delete"variant="destructive"diff --git a/docs/families/buttons.md b/docs/families/buttons.mdindex 523afaccbf..d86069b931 100644--- a/docs/families/buttons.md+++ b/docs/families/buttons.md@@ -26,7 +26,11 @@ members:component:ToggleButtonGroup,]architecture:- [architecture:component-theming-surface, architecture:public-component-api]+ [+ architecture:component-size-cascade,+ architecture:component-theming-surface,+ architecture:public-component-api,+ ]contributing: []deciding_specs: [spec:AST-002/DEC-1]---@@ -134,8 +138,11 @@ Membership follows public responsibility, not an import of Button or a renderedderive from the effective in-flight value rather than a stale committed value.- **FR7 — Shared size preserves family geometry.** Members using the family sizeaxis MUST map `sm`, `md`, and `lg` to the same control-height contract. An- icon-only member is square at the resolved size. Label weight, pressed state,- loading, or icon replacement MUST NOT change its outer dimensions.+ icon-only member is square at the resolved size. Button and IconButton MUST+ default an Astryx Icon in their owned icon slot to `sm` for `sm` and `md`+ controls and to `md` for `lg` controls; an explicit Icon size MUST win. Label+ weight, pressed state, loading, or icon replacement MUST NOT change the outer+ control dimensions.- **FR8 — Elevation belongs to the painted surface.** A standalone member thatpaints its visible surface owns its resting elevation. A connected group thatpaints one continuous surface owns one shared elevation and its members paintdiff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex 962fd62cd7..36f5e7a547 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/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',@@ -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',diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsxindex c9c15fe57c..edcdc2d914 100644--- a/packages/core/src/Button/Button.tsx+++ b/packages/core/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 : (diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsindex b4a8637215..25643174bd 100644--- a/packages/core/src/Icon/Icon.doc.mjs+++ b/packages/core/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:diff --git a/packages/core/src/Icon/Icon.spec.md b/packages/core/src/Icon/Icon.spec.mdindex 189f1041c5..712cf76b24 100644--- a/packages/core/src/Icon/Icon.spec.md+++ b/packages/core/src/Icon/Icon.spec.md@@ -10,12 +10,18 @@ approved_by: cixzhangapproved_at: 2026-08-30owners: [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 defaultConsumer 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 tothe 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 sharedicon 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 itdecorative — 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 isexisting 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 anintentional 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 iconsource 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 oruse an internal wrapper for a resolved key; neither element shape is publicanatomy.- **AV3 — Theme and consumer styling.** Existing theme and styling escape hatchesmay 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 supportedpass-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. Currentimplementation 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 validationrules for the `icon` target.- `architecture:icon-resolution-and-component-slots` owns semantic-key andcomponent-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 describeimplementation 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 questionsNone.diff --git a/packages/core/src/Icon/Icon.test.tsx b/packages/core/src/Icon/Icon.test.tsxindex 10df5cb27d..d64c15630c 100644--- a/packages/core/src/Icon/Icon.test.tsx+++ b/packages/core/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', () => {diff --git a/packages/core/src/Icon/Icon.tsx b/packages/core/src/Icon/Icon.tsxindex 818f36aa72..415054c4fb 100644--- a/packages/core/src/Icon/Icon.tsx+++ b/packages/core/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,diff --git a/packages/core/src/Icon/IconDefaultSizeContext.ts b/packages/core/src/Icon/IconDefaultSizeContext.tsnew file mode 100644index 0000000000..2415b3a417--- /dev/null+++ b/packages/core/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';+}diff --git a/packages/core/src/Icon/IconSize.stylex.ts b/packages/core/src/Icon/IconSize.stylex.tsnew file mode 100644index 0000000000..b2298707da--- /dev/null+++ b/packages/core/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,+ },+});diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjsindex 81342e0b1e..a9636f2702 100644--- a/packages/core/src/IconButton/IconButton.doc.mjs+++ b/packages/core/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)',diff --git a/packages/core/src/IconButton/IconButton.test.tsx b/packages/core/src/IconButton/IconButton.test.tsxindex 275c6ca20a..c22c4fe6e4 100644--- a/packages/core/src/IconButton/IconButton.test.tsx+++ b/packages/core/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();