@astryxdesign/core 0.1.7-canary.9da0792 → 0.1.7-canary.a82fbd9

package/README.md

@@ -2,18 +2,27 @@
 
 Core UI components, theme system, and utilities for the Astryx design system. For project setup, see [Quick Start](#quick-start) below.
 
-> **Building with an AI agent?** Run **`npx astryx init`** first. It installs the Astryx CLI's component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Without it, agents can't see the CLI — see [XDS CLI](#xds-cli).
+> **Building with an AI agent?** Add the CLI, then run `init`:
+>
+> ```bash
+> npm install -D @astryxdesign/cli   # or: pnpm add -D / yarn add -D / bun add -d
+> npx astryx init                    # resolves to the CLI you just installed
+> ```
+>
+> `init` writes the Astryx component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? Use the scoped package directly — `npx @astryxdesign/cli <cmd>` (or `pnpm dlx`/`bunx @astryxdesign/cli`). Bare `npx astryx` only works once `@astryxdesign/cli` is a dependency; before that npm resolves it to an unrelated package. See [XDS CLI](#xds-cli).
 
 ## Component Docs
 
-Look up any component's full API (props, types, best practices, and theming):
+Look up any component's full API (props, variants, examples, best practices, and theming) via the Astryx CLI:
 
 ```bash
-node node_modules/@astryxdesign/core/docs.mjs Button        # full docs for a component
-node node_modules/@astryxdesign/core/docs.mjs --list         # list all components
-node node_modules/@astryxdesign/core/docs.mjs --list --brief  # brief summaries
+npx @astryxdesign/cli init                   # one-time: writes the component guide into AGENTS.md / CLAUDE.md
+npx @astryxdesign/cli component Button        # full docs for a component
+npx @astryxdesign/cli component --list        # list all components
 ```
 
+> Use the scoped `@astryxdesign/cli` to run without installing; bare `npx astryx` only resolves once the CLI is a dependency.
+
 ## Page Layouts
 
 Building a full page? Start with a template rather than composing from scratch.
@@ -25,9 +34,9 @@ global navigation.
 Requires `@astryxdesign/cli` (`npm install -D @astryxdesign/cli`):
 
 ```bash
-npx astryx template --list              # browse all page and block templates
-npx astryx template dashboard           # emit full page source
-npx astryx template settings --skeleton # layout skeleton with spatial annotations
+astryx template --list              # browse all page and block templates
+astryx template dashboard           # emit full page source
+astryx template settings --skeleton # layout skeleton with spatial annotations
 ```
 
 ## Astryx CLI
@@ -35,19 +44,21 @@ npx astryx template settings --skeleton # layout skeleton with spatial annotatio
 The CLI (`@astryxdesign/cli`) provides additional tooling:
 
 ```bash
-npx astryx --help                       # full listing of all commands
-npx astryx component Button             # full docs + related block templates
-npx astryx docs                         # reference docs (principles, tokens, theming, styling)
-npx astryx docs theme                   # theming guide (Theme, defineTheme, light/dark)
-npx astryx docs tokens                  # spacing, color, radius, typography token reference
-npx astryx init                         # initialize Astryx in your project
-npx astryx theme build                  # build theme CSS for production
-npx astryx swizzle Button               # eject component source for customization
-npx astryx upgrade --apply              # run codemods to migrate between versions
-npx astryx discover                     # discover external Astryx packages
-npx astryx gap-report                   # report a missing capability
+astryx --help                       # full listing of all commands
+astryx component Button             # full docs + related block templates
+astryx docs                         # reference docs (principles, tokens, theming, styling)
+astryx docs theme                   # theming guide (Theme, defineTheme, light/dark)
+astryx docs tokens                  # spacing, color, radius, typography token reference
+astryx init                         # initialize Astryx in your project
+astryx theme build                  # build theme CSS for production
+astryx swizzle Button               # eject component source for customization
+astryx upgrade --apply              # run codemods to migrate between versions
+astryx discover                     # discover external Astryx packages
+astryx gap-report                   # report a missing capability
 ```
 
+> Prefix these with your runner: `npx astryx …` / `pnpm exec astryx …` once the CLI is installed, or `npx @astryxdesign/cli …` to run without installing.
+
 ## Related Packages
 
 | Package                                                                                               | Description                                                   |

package/dist/Avatar/Avatar.d.ts

@@ -13,9 +13,13 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
-type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
+type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 /**
  * Numeric size options (in pixels)
  */
@@ -52,8 +56,9 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
      */
     name?: string;
     /**
-     * The size of the avatar.
-     * @default 'small'
+     * The size of the avatar. A named size (`xsm` 20px, `sm` 24px, `md` 36px,
+     * `lg` 48px, `xl` 128px) or a specific pixel value.
+     * @default 'md'
      */
     size?: AvatarSize;
     /**
@@ -75,7 +80,7 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */

package/dist/Avatar/Avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsC5C;;GAEG;AACH,KAAK,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExE;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAqFD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAc,EACd,GAAG,EACH,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwFb;yBArGe,MAAM"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsC5C;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAqFD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAW,EACX,GAAG,EACH,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwFb;yBArGe,MAAM"}

package/dist/Avatar/Avatar.js

@@ -50,7 +50,11 @@ const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 const INITIALS_FONT_SIZE_RATIO = 0.4;
 
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
 
 /**
@@ -69,15 +73,15 @@ export function resolveSize(size) {
     return size;
   }
   switch (size) {
-    case 'tiny':
+    case 'xsm':
       return 20;
-    case 'xsmall':
+    case 'sm':
       return 24;
-    case 'small':
+    case 'md':
       return 36;
-    case 'medium':
+    case 'lg':
       return 48;
-    case 'large':
+    case 'xl':
       return 128;
   }
 }
@@ -223,7 +227,7 @@ function DefaultIcon({
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */
@@ -232,7 +236,7 @@ export function Avatar({
   'data-testid': testId,
   fallbackSrc,
   name,
-  size = 'small',
+  size = 'md',
   src,
   status,
   xstyle,

package/dist/Avatar/AvatarSizeContext.d.ts

@@ -2,7 +2,7 @@
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export declare const AvatarSizeContext: import("react").Context<number>;
 //# sourceMappingURL=AvatarSizeContext.d.ts.map

package/dist/Avatar/AvatarSizeContext.js

@@ -17,7 +17,7 @@ import { createContext } from 'react';
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export const AvatarSizeContext = /*#__PURE__*/createContext(36);
 AvatarSizeContext.displayName = 'AvatarSizeContext';

package/dist/Avatar/AvatarStatusDot.d.ts

@@ -76,12 +76,12 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/dist/Avatar/AvatarStatusDot.js

@@ -148,12 +148,12 @@ const variantStyleMap = {
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/dist/AvatarGroup/AvatarGroup.d.ts

@@ -27,7 +27,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
     children: ReactNode;
     /**
      * Size applied to all avatars via context.
-     * @default 'small'
+     * @default 'md'
      */
     size?: AvatarSize;
     /**
@@ -45,7 +45,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/AvatarGroup/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AASvD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAc,EACd,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA6B9B;yBAvCe,WAAW"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AASvD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA6B9B;yBAvCe,WAAW"}

package/dist/AvatarGroup/AvatarGroup.js

@@ -44,7 +44,7 @@ const styles = {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}
@@ -54,7 +54,7 @@ const styles = {
  */
 export function AvatarGroup({
   children,
-  size = 'small',
+  size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   xstyle,

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts

@@ -33,7 +33,7 @@ export interface AvatarGroupOverflowProps extends Omit<BaseProps<HTMLElement>, '
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA6DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}
+{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAW5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA4ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}

package/dist/AvatarGroup/AvatarGroupOverflow.js

@@ -15,7 +15,7 @@
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { colorVars, typographyVars, fontWeightVars, radiusVars } from "../theme/tokens.stylex.js";
+import { colorVars, typographyVars, fontWeightVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { useAvatarGroup } from "./AvatarGroupContext.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -37,13 +37,14 @@ const styles = {
     kMzoRj: "xdh2fpr",
     ksu8eU: "x1y0btm7",
     kVAM5u: "x1touxvs",
-    kB7OPa: "x1afcbsf",
+    kB7OPa: "x9f619",
+    kg3NbH: "xf314gf",
     kKwaWg: "x14bno8m",
     $$css: true
   },
   button: {
     kkrTdU: "x1ypdohk",
-    kmVPX3: "x1717udv",
+    k8WAf4: "xt970qd",
     kKwaWg: "x14bno8m xbfmc0r x1nocapi",
     kI3sdo: "x1a2a7pz x17nn4n9",
     kInvED: "x7s97pk",
@@ -55,26 +56,27 @@ const styles = {
   }
 };
 const _temp = {
-  kGuDYH: "xdmh292",
+  k7Eaqz: "xkj4a21",
+  kZKoxP: "x16ye13r",
   "$$css": true
 };
 const _temp2 = {
+  kGuDYH: "xdmh292",
+  "$$css": true
+};
+const _temp3 = {
   "--_avatar-group-overlap": "xlz5hwt",
   "$$css": true
 };
 const dynamicStyles = {
-  size: s => [{
-    kzqmXN: s != null ? "x5lhr3w" : s,
-    kZKoxP: s != null ? "x16ye13r" : s,
-    $$css: true
-  }, {
-    "--x-width": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s),
-    "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s)
+  size: s => [_temp, {
+    "--x-minWidth": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s + BORDER_WIDTH * 2),
+    "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s + BORDER_WIDTH * 2)
   }],
-  fontSize: s => [_temp, {
+  fontSize: s => [_temp2, {
     "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s * OVERFLOW_FONT_RATIO)
   }],
-  overlap: offset => [_temp2, {
+  overlap: offset => [_temp3, {
     "--x---_avatar-group-overlap": `${offset}px` != null ? `${offset}px` : undefined
   }]
 };
@@ -85,7 +87,7 @@ const dynamicStyles = {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/Carousel/Carousel.d.ts

@@ -3,8 +3,9 @@
  * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
  * @output Exports Carousel component
  * @position Horizontal scroll container with fade-edge overflow indication,
- *   optional prev/next buttons on the top layer, scroll-snap, and a 1px
- *   visual bleed allowance for child selection indicators.
+ *   optional prev/next buttons on the top layer, scroll-snap, a 1px
+ *   visual bleed allowance for child selection indicators, and Shift + wheel
+ *   mapping so mouse users can scroll horizontally.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA2C,MAAM,OAAO,CAAC;AAc/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAmJf;yBAjKe,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA2C,MAAM,OAAO,CAAC;AAc/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BA6Kf;yBA3Le,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -7,8 +7,9 @@
  * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
  * @output Exports Carousel component
  * @position Horizontal scroll container with fade-edge overflow indication,
- *   optional prev/next buttons on the top layer, scroll-snap, and a 1px
- *   visual bleed allowance for child selection indicators.
+ *   optional prev/next buttons on the top layer, scroll-snap, a 1px
+ *   visual bleed allowance for child selection indicators, and Shift + wheel
+ *   mapping so mouse users can scroll horizontally.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)
@@ -234,6 +235,34 @@ export function Carousel({
     scrollElRef.current = el;
     scrollRef(el);
   }, [scrollRef]);
+
+  // Map Shift + vertical wheel to horizontal scroll. Trackpads emit
+  // horizontal deltas natively, but a standard mouse only produces deltaY —
+  // so mouse users can't wheel-scroll a horizontal container. Shift + wheel
+  // is the long-established convention for horizontal scroll containers; we
+  // honor it by translating the vertical delta into a horizontal scroll.
+  //
+  // Only kicks in when Shift is held and the wheel is purely vertical
+  // (deltaX === 0), so native trackpad horizontal scrolling is untouched.
+  const handleWheel = useCallback(event => {
+    if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {
+      return;
+    }
+    const el = scrollElRef.current;
+    if (!el) {
+      return;
+    }
+    // Nothing to scroll horizontally — let the event fall through so the page
+    // can scroll as it normally would.
+    if (el.scrollWidth <= el.clientWidth) {
+      return;
+    }
+    event.preventDefault();
+    el.scrollBy({
+      left: event.deltaY,
+      behavior: 'auto'
+    });
+  }, []);
   const scrollBy = useCallback(direction => {
     const el = scrollElRef.current;
     if (!el) {
@@ -271,6 +300,7 @@ export function Carousel({
     children: [/*#__PURE__*/_jsx("div", {
       ref: composedRef,
       tabIndex: 0,
+      onWheel: handleWheel,
       ...stylex.props(styles.scroller, gapStyles[gap], padding != null && paddingStyles[padding], hasSnap && styles.snap, fadeStyle),
       children: Children.map(children, child => /*#__PURE__*/_jsx("div", {
         ...{

package/dist/Chat/ChatMessage.d.ts

@@ -46,7 +46,7 @@ export interface ChatMessageProps extends BaseProps<HTMLElement> {
  *
  * @example
  * ```
- * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="small" />}>
+ * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="md" />}>
  *   <ChatMessageBubble>Hello!</ChatMessageBubble>
  *   <ChatMessageMetadata timestamp="2:30 PM" />
  * </ChatMessage>

package/dist/Chat/ChatMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BAyFlB;yBAtGe,WAAW"}
+{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BA2FlB;yBAxGe,WAAW"}

package/dist/Chat/ChatMessage.js

@@ -122,7 +122,7 @@ const styles = {
  *
  * @example
  * ```
- * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="small" />}>
+ * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="md" />}>
  *   <ChatMessageBubble>Hello!</ChatMessageBubble>
  *   <ChatMessageMetadata timestamp="2:30 PM" />
  * </ChatMessage>

package/dist/Icon/Icon.d.ts

@@ -140,6 +140,31 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
      * @default 'md'
      */
     size?: IconSize;
+    /**
+     * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
+     * its own — a standalone status glyph or an icon-only indicator with no
+     * adjacent text conveying the same information. Providing it exposes the icon
+     * to assistive tech as `role="img"` with this string as the accessible name
+     * (via `aria-label`) and drops the default `aria-hidden="true"`.
+     *
+     * Omit it (the default) for decorative icons — the common case, e.g. an icon
+     * beside a text label — and the icon stays hidden from assistive tech
+     * (`aria-hidden="true"`). An empty string (`''`) is treated the same as
+     * omitting it (decorative), since an empty accessible name is meaningless.
+     *
+     * Don't set `label` when an interactive parent (Button, IconButton, link)
+     * already names the control — that produces a duplicate announcement.
+     *
+     * @example
+     * ```
+     * // Meaningful, standalone icon
+     * <Icon icon="success" label="Completed" />
+     *
+     * // Decorative icon (default) — omit label
+     * <Icon icon="search" />
+     * ```
+     */
+    label?: string;
 }
 /**
  * Renders an icon from the icon registry or a custom SVG component.
@@ -149,7 +174,7 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
  * <Icon icon="close" size="md" color="primary" />
  * ```
  */
-export declare function Icon({ icon, color, size, ref, ...props }: IconProps): React.JSX.Element;
+export declare function Icon({ icon, color, size, label, ref, ...props }: IconProps): React.JSX.Element;
 export declare namespace Icon {
     var displayName: string;
 }

package/dist/Icon/Icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAyCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBA0BX;yBAhCe,IAAI;;;AAiFpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAyCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBAkCX;yBAzCe,IAAI;;;AA4FpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}

package/dist/Icon/Icon.js

@@ -205,6 +205,26 @@ const spanSizeStyles = {
  * Extends SVGProps to allow passing additional SVG attributes (used when icon is a component).
  */
 
+/**
+ * Derives the ARIA attributes for an icon from its `label` prop.
+ *
+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
+ *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
+ *   tree, so its accessible name would be ignored).
+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
+ *
+ * The result is spread BEFORE `{...props}` in both render modes so an explicit
+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
+ */
+function getIconA11yProps(label) {
+  return label != null && label !== '' ? {
+    role: 'img',
+    'aria-label': label
+  } : {
+    'aria-hidden': 'true'
+  };
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -221,15 +241,21 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }) {
+  // 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);
+
   // String mode: resolve from icon registry, wrap in styled span
   if (typeof icon === 'string') {
     return /*#__PURE__*/_jsx(IconFromRegistry, {
       name: icon,
       color: color,
       size: size,
+      a11yProps: a11yProps,
       spanProps: props
     });
   }
@@ -237,8 +263,12 @@ export function Icon({
   // Component mode: render SVG component directly with ref forwarding
   const IconComponent = icon;
   return /*#__PURE__*/_jsx(IconComponent, {
-    ref: ref,
-    "aria-hidden": "true",
+    ref: ref
+    // Derived a11y (decorative default or meaningful `label`) is spread
+    // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
+    // consumer still wins as an escape hatch.
+    ,
+    ...a11yProps,
     ...mergeProps(themeProps('icon', {
       size,
       color
@@ -263,6 +293,7 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps
 }) {
   const resolvedIcon = getIcon(name);
@@ -270,11 +301,7 @@ function IconFromRegistry({
     return null;
   }
   return /*#__PURE__*/_jsx("span", {
-    // Decorative by default, but placed BEFORE the prop spread so consumers
-    // can override it (e.g. `aria-hidden={false}` + `role="img"` +
-    // `aria-label`) to expose a meaningful standalone icon. This matches
-    // component-mode Icon, which already sets aria-hidden before its spread.
-    "aria-hidden": "true",
+    ...a11yProps,
     ...spanProps,
     ...mergeProps(themeProps('icon', {
       size,