@astryxdesign/core 0.7.4 → 0.7.5-canary.0026f37

package/dist/utils/dateParser.d.ts

@@ -8,9 +8,9 @@
  * - /packages/core/src/utils/dateParser.test.ts
  * - /packages/core/src/utils/index.ts
  */
-import { type PlainDate } from './plainDate';
-import type { Locale } from '../i18n/types';
-export { plainDateFromISO as parseISO, plainDateToISO as dateToISO, } from './plainDate';
+import { type PlainDate } from './plainDate.js';
+import type { Locale } from '../i18n/types.js';
+export { plainDateFromISO as parseISO, plainDateToISO as dateToISO, } from './plainDate.js';
 /**
  * Detects if the locale uses day-first date format (DD/MM/YYYY).
  * US and a few others use month-first (MM/DD/YYYY).

package/dist/utils/groupItems.d.ts

@@ -5,7 +5,7 @@
  * @position Shared utility; used by CommandPalette, trigger menu, and
  *   any future component that needs to group search results by category.
  */
-import type { SearchableItem } from '../Typeahead/types';
+import type { SearchableItem } from '../Typeahead/types.js';
 /**
  * A group of items with an optional heading.
  * `heading` is null for ungrouped items.

package/dist/utils/index.d.ts

@@ -4,33 +4,33 @@
  * @output Re-exports all utility functions and shared types
  * @position Package entry point for utils
  */
-export type { SizeValue } from './types';
-export type { ISODateString, DayOfWeek, PlainDate, DateRange } from './dateTypes';
-export { parseDateInput, dateToISO, parseISO, isLocaleDayFirst, } from './dateParser';
-export { plainDateCreate, plainDateFromISO, plainDateToISO, plainDateToDate, plainDateFromDate, plainDateToday, getDaysInMonth, plainDateDayOfWeek, plainDateAddMonths, plainDateAddDays, plainDateToInstant, plainDateFromInstant, plainDateIsBefore, plainDateIsAfter, plainDateIsEqual, plainDateMax, plainDateMin, plainDateIsInRange, plainDateSetFirstOfMonth, plainDateSetStartOfWeek, plainDateSetEndOfWeekExclusive, plainDateGetWeekNumber, plainDateFormat, formatSharedDate, DATE_FORMAT_WITH_WEEKDAY, DATE_FORMAT_SHORT_WITH_WEEKDAY, DATE_FORMAT_LONG, DATE_FORMAT_MONTH_YEAR, DATE_FORMAT_MONTH_ONLY, DATE_FORMAT_WEEKDAY_ONLY, DATE_FORMAT_SHORT, DATE_FORMAT_SHORT_WITH_YEAR, SHARED_DATE_FORMAT_OPTIONS, } from './plainDate';
-export type { SharedDateFormat } from './plainDate';
-export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h, parseTimeInput, compareTime, isTimeInRange, clampTime, adjustTime, createISOTimeString, } from './timeParser';
-export type { ISOTimeString, ParsedTime } from './timeParser';
-export { parseStyleKey } from './parseStyleKey';
-export { getKey, type Key, type KeyFallback } from './getKey';
-export { characterCount, firstCharacter, truncateCharacters } from './characters';
-export { mergeProps } from './mergeProps';
-export { mergeRefs } from './mergeRefs';
-export { isFocusDetached } from './focusReturn';
-export { composeEventHandlers } from './composeEventHandlers';
-export { themeProps, themeDataAttributes } from './themeProps';
-export type { ClassValue, ClassProps, ThemeDataAttributes, ThemeProps, } from './themeProps';
-export { groupItems, getItemGroup } from './groupItems';
-export type { ItemGroup, GroupItemsOptions } from './groupItems';
-export { observeResize, unobserveResize } from './sharedResizeObserver';
-export { isRenderable } from './isRenderable';
-export { getInputARIA } from './inputAria';
-export type { InputARIA, InputARIAInputGroup } from './inputAria';
-export { parseHex, parseRgb, parseColor, formatHex, formatColor, toGLFloats, } from './color';
-export type { RGBA } from './color';
-export { devWarn, devError, warnOnce, formatDevMessage } from './devWarning';
-export { rtlStyles } from './rtlStyles';
-export { focusOutlineStyles, focusOutlineProps } from './focusOutline.stylex';
-export { isImeKeyEvent } from './ime';
-export { interactionOverlayStyles } from './interactionOverlay.stylex';
+export type { SizeValue } from './types.js';
+export type { ISODateString, DayOfWeek, PlainDate, DateRange } from './dateTypes.js';
+export { parseDateInput, dateToISO, parseISO, isLocaleDayFirst, } from './dateParser.js';
+export { plainDateCreate, plainDateFromISO, plainDateToISO, plainDateToDate, plainDateFromDate, plainDateToday, getDaysInMonth, plainDateDayOfWeek, plainDateAddMonths, plainDateAddDays, plainDateToInstant, plainDateFromInstant, plainDateIsBefore, plainDateIsAfter, plainDateIsEqual, plainDateMax, plainDateMin, plainDateIsInRange, plainDateSetFirstOfMonth, plainDateSetStartOfWeek, plainDateSetEndOfWeekExclusive, plainDateGetWeekNumber, plainDateFormat, formatSharedDate, DATE_FORMAT_WITH_WEEKDAY, DATE_FORMAT_SHORT_WITH_WEEKDAY, DATE_FORMAT_LONG, DATE_FORMAT_MONTH_YEAR, DATE_FORMAT_MONTH_ONLY, DATE_FORMAT_WEEKDAY_ONLY, DATE_FORMAT_SHORT, DATE_FORMAT_SHORT_WITH_YEAR, SHARED_DATE_FORMAT_OPTIONS, } from './plainDate.js';
+export type { SharedDateFormat } from './plainDate.js';
+export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h, parseTimeInput, compareTime, isTimeInRange, clampTime, adjustTime, createISOTimeString, } from './timeParser.js';
+export type { ISOTimeString, ParsedTime } from './timeParser.js';
+export { parseStyleKey } from './parseStyleKey.js';
+export { getKey, type Key, type KeyFallback } from './getKey.js';
+export { characterCount, firstCharacter, truncateCharacters } from './characters.js';
+export { mergeProps } from './mergeProps.js';
+export { mergeRefs } from './mergeRefs.js';
+export { isFocusDetached } from './focusReturn.js';
+export { composeEventHandlers } from './composeEventHandlers.js';
+export { themeProps, themeDataAttributes } from './themeProps.js';
+export type { ClassValue, ClassProps, ThemeDataAttributes, ThemeProps, } from './themeProps.js';
+export { groupItems, getItemGroup } from './groupItems.js';
+export type { ItemGroup, GroupItemsOptions } from './groupItems.js';
+export { observeResize, unobserveResize } from './sharedResizeObserver.js';
+export { isRenderable } from './isRenderable.js';
+export { getInputARIA } from './inputAria.js';
+export type { InputARIA, InputARIAInputGroup } from './inputAria.js';
+export { parseHex, parseRgb, parseColor, formatHex, formatColor, toGLFloats, } from './color.js';
+export type { RGBA } from './color.js';
+export { devWarn, devError, warnOnce, formatDevMessage } from './devWarning.js';
+export { rtlStyles } from './rtlStyles.js';
+export { focusOutlineStyles, focusOutlineProps } from './focusOutline.stylex.js';
+export { isImeKeyEvent } from './ime.js';
+export { interactionOverlayStyles } from './interactionOverlay.stylex.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/plainDate.d.ts

@@ -4,9 +4,9 @@
  * @output Immutable PlainDate records and pure date arithmetic
  * @position Shared utility; replaces scattered Date usage across Calendar hooks
  */
-import type { ISODateString, PlainDate } from './dateTypes';
-import type { Locale } from '../i18n/types';
-export type { PlainDate } from './dateTypes';
+import type { ISODateString, PlainDate } from './dateTypes.js';
+import type { Locale } from '../i18n/types.js';
+export type { PlainDate } from './dateTypes.js';
 export declare function plainDateCreate(year: number, month: number, day: number): PlainDate;
 export declare function plainDateFromISO(str: ISODateString): PlainDate;
 export declare function plainDateToISO(pd: PlainDate): ISODateString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.4",
+  "version": "0.7.5-canary.0026f37",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,6 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.5-canary.0026f37",
+    "@astryxdesign/cli": "0.7.5-canary.0026f37",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -802,16 +804,14 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.4"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "build": "node ../../scripts/clean-dist.mjs && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
+    "build": "node ../../scripts/clean-dist.mjs && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && node ../../scripts/add-declaration-extensions.mjs && pnpm build:css && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
     "build:i18n": "node ../../scripts/generate-i18n-runtime.mjs && node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",
     "build:css": "node ../../scripts/build-css.mjs",

package/src/Badge/Badge.doc.mjs

@@ -18,6 +18,7 @@ export const docs = {
     {
       name: 'label',
       type: 'ReactNode',
+      required: true,
       description:
         'Badge text content. A badge is one line, so a label wider than the space available is cut with an ellipsis rather than escaping its container; a string or number label is also set as the badge\'s title so the full text stays reachable on hover.',
     },
@@ -93,7 +94,7 @@ export const docsZh = {
       description: '视觉样式变体。语义变体使用实色背景，非语义颜色变体使用浅色背景配彩色文字。',
       default: "'neutral'",
     },
-    {name: 'label', type: 'ReactNode', description: '徽章文本内容。'},
+    {name: 'label', type: 'ReactNode', required: true, description: '徽章文本内容。'},
     {name: 'icon', type: 'ReactNode', description: '可选的前置图标。'},
   ],
   theming: {

package/src/BottomSheet/BottomSheet.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, core hooks, shared layer dismissal, the shared interaction modality, named BottomSheetPanel, BottomSheetSwitcherContext
+ * @input Uses React, StyleX, core hooks, shared layer dismissal, the modal outlet registry, the shared interaction modality, named BottomSheetPanel, BottomSheetSwitcherContext
  * @output Exports BottomSheet component and BottomSheetProps
  * @position Public BottomSheet router plus private standalone/switcher hosts
  *
@@ -27,6 +27,9 @@
  * in a switcher, handing one scrim between two dialogs and keeping focus in
  * the active sheet when a retained dialog closes.
  *
+ * While a standalone modal sheet is open, its dialog is the outlet that
+ * app-global surfaces (toasts) render into (Layer/modalOutlet.ts).
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
  * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
@@ -36,6 +39,7 @@
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/Layer/layerDismissalFamilies.test.tsx
  * - /packages/core/src/Layer/layerDismissalInvariants.test.tsx
+ * - /packages/core/src/Toast/ToastViewport.modalHost.test.tsx
  * - /apps/storybook/stories/BottomSheet.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.tsx
  */
@@ -58,6 +62,7 @@ import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {useDevWarning, useScrollLock} from '../hooks';
 import {mergeProps} from '../utils';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useModalOutlet} from '../Layer/modalOutlet';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
@@ -373,6 +378,12 @@ function StandaloneBottomSheet({
     }
   }, [hasScrim, isOpen]);
 
+  // Host app-global surfaces (toasts) inside this sheet while it is an open
+  // modal, so they stay visible and operable above it. A closing sheet stays
+  // modal through its exit animation, but inert and hidden, so it hands them
+  // back as soon as it starts closing.
+  useModalOutlet(dialogRef, isOpen && hasScrim);
+
   useEffect(() => {
     if (!isOpen && isPresented && hasScrim) {
       handleScrimOpacity(0);

package/src/BottomSheet/__tests__/BottomSheetToastOutlet.a11y.chromium.spec.ts

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetToastOutlet.a11y.chromium.spec.ts
+ * @input The built Core/Toast AppToastOverBottomSheet story; real Chromium hit
+ *   testing and mouse input
+ * @output Browser evidence that a toast fired from an open BottomSheet, on its
+ *   own or over a Dialog, is hit-testable above the sheet and takes a click
+ * @position Chromium proof for BottomSheet's modal outlet
+ *   (Layer/modalOutlet.ts). jsdom has no top layer and no modal inertness, so
+ *   Toast/ToastViewport.modalHost.test.tsx can only check where the viewport
+ *   lives.
+ */
+
+import {expect, test} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+// Phone width: where an app presents its dialogs as bottom sheets.
+test.use({viewport: {width: 390, height: 844}});
+
+const SCENARIOS = [
+  {name: 'on its own', opens: ['Open sheet']},
+  {name: 'over a Dialog', opens: ['Open dialog', 'Open sheet from the dialog']},
+];
+
+for (const {name, opens} of SCENARIOS) {
+  test(`a toast action above a sheet opened ${name} takes the click`, async ({
+    page,
+  }) => {
+    await page.goto(
+      `${storybook.origin}/iframe.html?id=core-toast--app-toast-over-bottom-sheet&viewMode=story`,
+    );
+    await holdMotionStill(page);
+    for (const label of opens) {
+      await page.getByRole('button', {name: label, exact: true}).click();
+    }
+    const sheet = page.getByRole('dialog', {name: 'Item actions'});
+    await expect(sheet).toBeVisible();
+    await sheet.getByRole('button', {name: 'Archive'}).click();
+    await expect(sheet.getByText('The item is archived.')).toBeVisible();
+
+    const undo = page.locator('[popover] button', {hasText: 'Undo'});
+    await expect(undo).toBeVisible();
+    const box = await undo.boundingBox();
+    if (box == null) {
+      throw new Error('the Undo button has no box');
+    }
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+
+    // Hit testing skips inert content and follows top-layer order: a toast
+    // left outside the sheet's modal, or under it, loses this point to the
+    // sheet.
+    const hit = await page.evaluate(
+      ([px, py]) =>
+        document.elementFromPoint(px, py)?.closest('button')?.textContent ??
+        null,
+      [x, y],
+    );
+    expect(hit).toBe('Undo');
+
+    await page.mouse.click(x, y);
+    await expect(
+      sheet.getByText('The item is back in your inbox.'),
+    ).toBeVisible();
+  });
+}

package/src/Field/inputDisabledFocus.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file inputDisabledFocus.ts
+ * @input Uses StyleX and theme tokens
+ * @output inputDisabledFocusStyles (internal; not re-exported from Field/index.ts)
+ * @position Field wrapper style shared by TextInput and TextArea
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+export const inputDisabledFocusStyles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while the field's
+  // own control, a direct child, has keyboard focus (`spec:AST-085` FR6), so a
+  // focused status button keeps only its own outline.
+  ring: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(> [aria-disabled="true"]:focus-visible)':
+        colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
+});

package/src/Icon/Icon.spec.md

@@ -27,7 +27,7 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-087]
 ---
 
 # Icon component contract
@@ -53,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.
+- Passing the resolved size and a variant the entry can receive to a registry entry.
 - Resolving explicit, component-owned contextual, and standalone size defaults.
 - Applying Icon's size, color, theming target, and accessibility semantics to
   the rendered glyph.
@@ -71,12 +72,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## 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                      | 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.              |
+| 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.                                         |
+| Variant       | names in `IconVariantMap`; the active theme lists its own | Requests a theme's alternate artwork for a registry glyph. | Registry glyphs only; never a supplied component | None                                            | `component:Icon` | Stable    | TypeScript rejects unknown names; an unlisted variant renders the normal artwork. |
 
 A namespaced key that does not resolve currently renders nothing. This is
 existing behavior, not an intentional fallback promise.
@@ -86,13 +88,15 @@ 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 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.                                         |
+| 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.                                         |
+| FR6 | In registry mode, Icon MUST pass `{size, variant}` to the selected entry, where `size` is the size resolved by ORD1 and `variant` is the requested variant when the active theme lists it and, for a theme-supplied entry, the theme that defined the entry lists it too, otherwise `undefined`. A supplied icon component MUST NOT receive `variant`, Icon MUST NOT forward `variant` to the DOM, and the `icon` target MUST NOT reflect it. | `spec:AST-087` FR1–FR5 and FR9.                       | Settled intent.                                         |
+| FR7 | The `icon` target MUST guarantee `width` and `height` on its `size:*` selectors as reviewed target-specific additions, so a theme sets each size's dimension. Without theme styles, sizes are 12, 16, 20, and 24px at a 16px root and scale with the root font size.                                                                                                                                                                          | `spec:AST-087` FR10.                                  | Settled intent.                                         |
 
 ### Allowed variation
 
@@ -109,15 +113,18 @@ intentional decision.
 
 ### 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.    |
-| 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. |
+| 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. |
+| Listed variant                   | The entry receives the size and the variant when its defining theme also lists it. | The theme's artwork for that request.          |
+| Unlisted or omitted variant      | The entry receives `variant: undefined`.                                           | The theme's normal artwork.                    |
+| Variant on a supplied component  | The component renders as given without `variant`.                                  | Component implementation.                      |
 
 ### Transformation and precedence order
 
@@ -172,6 +179,8 @@ not promise a `span`, `svg`, or other element type.
   rules for the `icon` target.
 - `architecture:icon-resolution-and-component-slots` owns semantic-key and
   component-slot resolution before Icon renders the selected source.
+- `spec:AST-087` decides the `variant` request, theme-listed variant names, and
+  theme-set size dimensions.
 - `architecture:public-component-api` owns admission and compatibility rules for
   Icon's public props and observable defaults.
 - The owning component or family specifies each contextual Icon-size mapping.
@@ -181,12 +190,14 @@ not promise a `span`, `svg`, or other element type.
 
 ## Verification map
 
-| 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`       |
+| 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` |
+| FR6                 | `Icon.test.tsx` variant suites (pending)                                       | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior`      |
+| FR7                 | Theme styling tests for each size (pending)                                    | each size with and without theme styles                                                                          | A themed size does not change the glyph dimension, or an unstyled size changes.                                                               | `audit:Icon/theming`       |
+| 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-color` on both glyph source modes is a checkable test
 gap; source inspection is the current evidence for that part of FR2.

package/src/Layer/modalOutlet.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file modalOutlet.ts
- * @input The open Dialog `<dialog>` elements
+ * @input The open Dialog and scrim BottomSheet `<dialog>` elements
  * @output Exports useModalOutlet (a modal supplies its outlet),
  *   getActiveModalOutlet, and subscribeModalOutlets (a global host follows
  *   the latest one)

package/src/SideNav/SideNav.test.tsx

@@ -668,18 +668,27 @@ describe('SideNavHeading headerEndContent', () => {
     expect(screen.getByTestId('end-badge')).toBeInTheDocument();
   });
 
-  it('renders headerEndContent inside the link in isWholeHeadingLink path', () => {
+  it('renders headerEndContent beside the link, not inside it, in isWholeHeadingLink path', () => {
+    const onPress = vi.fn();
     render(
       <SideNavHeading
         heading="My App"
         headingHref="/home"
-        headerEndContent={<span data-testid="end-badge">3</span>}
+        headerEndContent={
+          <button type="button" onClick={onPress}>
+            Create
+          </button>
+        }
       />,
     );
-    const badge = screen.getByTestId('end-badge');
-    expect(badge).toBeInTheDocument();
-    // Badge renders inside the link
-    expect(badge.closest('a')).not.toBeNull();
+    const link = screen.getByRole('link', {name: 'My App'});
+    expect(link).toHaveAttribute('href', '/home');
+    // A control inside a link is invalid and its press would follow the link.
+    const button = screen.getByRole('button', {name: 'Create'});
+    expect(button.closest('a')).toBeNull();
+    expect(link.parentElement).toBe(button.parentElement?.parentElement);
+    fireEvent.click(button);
+    expect(onPress).toHaveBeenCalledTimes(1);
   });
 
   it('renders headerEndContent in isWholeHeadingTrigger path', () => {

package/src/SideNav/SideNavHeading.tsx

@@ -189,6 +189,17 @@ const styles = stylex.create({
     // today. The 28px min box still wins over Icon's width/height.
     fontSize: 'inherit',
   },
+  // The link part of a whole-heading link row that also has end content.
+  linkBesideEndContent: {
+    display: 'flex',
+    alignItems: 'center',
+    alignSelf: 'stretch',
+    gap: spacingVars['--spacing-2'],
+    flexGrow: 1,
+    minWidth: 0,
+    textDecoration: 'none',
+    color: 'inherit',
+  },
   headerEndContent: {
     flexShrink: 0,
     display: 'flex',
@@ -640,6 +651,36 @@ export function SideNavHeading({
     </button>
   );
 
+  // Whole heading is a link (no menu, single headingHref). End content may
+  // be a control, which must not sit inside the link (no interactive content
+  // in an <a>), so with end content the row is a div holding the link and the
+  // end content side by side, as the mixed mode does.
+  if (isWholeHeadingLink && headingHref && headerEndContentElement) {
+    return (
+      <div
+        ref={ref}
+        data-testid={testId}
+        {...mergeProps(
+          themeProps('side-nav-heading'),
+          stylex.props(styles.root, xstyle),
+          className,
+          style,
+        )}>
+        <LinkComponent
+          href={headingHref}
+          {...focusOutlineProps.focusVisible(
+            styles.linkBesideEndContent,
+            styles.menuTrigger,
+          )}
+          {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>
+          {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
+          {renderTextContent()}
+        </LinkComponent>
+        {headerEndContentElement}
+      </div>
+    );
+  }
+
   // Whole heading is a link (no menu, single headingHref)
   if (isWholeHeadingLink && headingHref) {
     return (

package/src/Stepper/Step.tsx

@@ -1316,6 +1316,10 @@ export function Step({
   const iconLabelNode = (
     <div {...stylex.props(styles.iconLabelRow)}>
       {(!isCompact || indicatorPosition !== 'on-track') && indicatorNode}
+      {/* A space between the indicator and the label: the row is a flex
+          container, which drops whitespace-only text, so nothing changes on
+          screen, but a text reading of the button then keeps "1 Account" as two
+          words instead of "1Account". */}{' '}
       <span
         {...mergeProps(
           labelThemeProps,
@@ -1576,6 +1580,8 @@ export function Step({
               )}
             />
           </div>
+          {/* Whitespace between the indicator column and the label, as in
+              iconLabelNode. */}{' '}
           <div {...stylex.props(styles.otBodyV)}>
             {labelLineNode}
             {otDescriptionNode}
@@ -1658,6 +1664,7 @@ export function Step({
             )}
           />
         </div>
+        {/* Whitespace between the rail and the label, as in iconLabelNode. */}{' '}
         {/* The on-track indicator remains visible as a node on the rail at
             compact widths, but the wrapper becomes presentational with its
             label. Navigation moves to the named controls in the summary row. */}

package/src/Stepper/Stepper.test.tsx

@@ -2016,3 +2016,36 @@ describe('step-label and step-description theme targets', () => {
     );
   });
 });
+
+describe('clickable step text reading', () => {
+  // axe-core's Label in Name rule joins a button's text nodes with nothing
+  // between them, aria-hidden ones included, so a number badge next to a label
+  // reads as one word ("1Account") that the step's name does not contain.
+  // Whitespace between them changes nothing on screen (the rows are flex
+  // containers) and keeps the two words apart.
+  it.each([
+    ['vertical', 'separated'],
+    ['horizontal', 'separated'],
+    ['vertical', 'on-track'],
+    ['horizontal', 'on-track'],
+  ] as const)(
+    'keeps the number and label apart in a %s %s step',
+    (orientation, indicatorPosition) => {
+      render(
+        <Stepper
+          orientation={orientation}
+          indicatorPosition={indicatorPosition}
+          activeStep={0}
+          label="Steps"
+          onStepClick={() => {}}>
+          <Step step={0} label="Account" indicator="number" />
+          <Step step={1} label="Payment" indicator="number" />
+        </Stepper>,
+      );
+
+      const button = screen.getByRole('button', {name: /Account/});
+      expect(button.textContent).toMatch(/1\s+Account/);
+      expect(button.textContent).not.toMatch(/1Account/);
+    },
+  );
+});