@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/Dialog/Dialog.tsx

@@ -52,6 +52,7 @@ import {LayerContentBoundary} from '../Layer/layerScopedContext';
 import {layerClickBoundary} from '../Layer/layerClickBoundary';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {useBackdropPress} from '../Layer/useBackdropPress';
 import {useModalOutlet} from '../Layer/modalOutlet';
 import {
   colorVars,
@@ -80,10 +81,12 @@ import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
-import {focusForLastInput} from '../utils/focusReturn';
+import {focusForLastInput, isFocusLost} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+
+type PointerHandler = (event: React.PointerEvent<HTMLDialogElement>) => void;
 /**
  * Calculate a directional translate offset for dialog entry animation.
  * Returns a normalized vector from the trigger element toward the viewport
@@ -186,8 +189,22 @@ const styles = stylex.create({
     position: 'fixed',
     margin: 'auto',
     padding: 0,
-    borderWidth: 0,
-    borderStyle: 'none',
+    // The backdrop does not blur the page. Forced colors override the
+    // backdrop's colour, so a 1px border keeps the modal separate from the
+    // page. It is a border, not an outline: the focus ring
+    // (focusOutlineProps) owns the outline longhands on this element.
+    borderWidth: {
+      default: 0,
+      '@media (forced-colors: active)': 1,
+    },
+    borderStyle: {
+      default: 'none',
+      '@media (forced-colors: active)': 'solid',
+    },
+    borderColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
     backgroundColor: colorVars['--color-background-surface'],
     '--_dialog-radius': radiusVars['--radius-container'],
     borderRadius: 'var(--_dialog-radius)',
@@ -233,11 +250,10 @@ const styles = stylex.create({
   openSettled: {
     animationName: 'none',
   },
-  // Backdrop using ::backdrop pseudo-element
+  // No backdrop-filter: a full-viewport blur is costly to repaint.
   backdrop: {
     '::backdrop': {
       backgroundColor: colorVars['--color-overlay'],
-      backdropFilter: 'blur(2px)',
     },
   },
   fullscreen: {
@@ -246,6 +262,8 @@ const styles = stylex.create({
     maxWidth: '100dvw',
     maxHeight: '100dvh',
     borderRadius: 0,
+    // Nothing of the page shows around a full-screen dialog: no edge.
+    borderWidth: 0,
     margin: 0,
     inset: 0,
   },
@@ -634,6 +652,42 @@ export function Dialog({
     }
   }, [isOpen, isInline]);
 
+  // A dialog that unmounts while open (rendered only while open, or removed
+  // with the rest of a view) never runs the close branch above, and removing a
+  // <dialog> does not run the browser's own focus return. Focus left inside
+  // it, or dropped to the body by the removal, goes back to the opener.
+  useEffect(() => {
+    if (isInline) {
+      return;
+    }
+    const dialog = dialogRef.current;
+    // Read now: a removed iframe's document has no window, so its frame
+    // element can no longer be found once the dialog is gone.
+    const host = dialog?.ownerDocument.defaultView?.frameElement ?? null;
+    return () => {
+      const trigger = triggerElementRef.current;
+      if (dialog == null || trigger == null) {
+        return;
+      }
+      // Checked once the commit has finished: StrictMode's simulated unmount
+      // leaves the dialog in the document, and only a real removal returns
+      // focus.
+      queueMicrotask(() => {
+        if (dialog.isConnected || !trigger.isConnected) {
+          return;
+        }
+        // isFocusLost reads the dialog's own document. For a dialog in an
+        // iframe, the document that hosts the frame must also have lost focus
+        // or keep it on that frame, wherever the opener is: a control the
+        // user pressed outside the frame to remove the dialog, or the frame
+        // itself, keeps its focus.
+        if (isFocusLost(dialog) && (host == null || isFocusLost(host))) {
+          focusForLastInput(trigger);
+        }
+      });
+    };
+  }, [isInline]);
+
   // Host app-global surfaces (toasts) inside this modal while it is open, so
   // they stay visible and operable above it.
   useModalOutlet(dialogRef, isOpen && !isInline);
@@ -687,16 +741,16 @@ export function Dialog({
     }
   }, [isOpen, isInline, hasConsumerName, titleId]);
 
-  // Handle backdrop click — when the user clicks the ::backdrop pseudo-element,
-  // the event target is the <dialog> element itself; clicks on child content
-  // always target the child. This avoids false positives from native browser
+  // A press on the ::backdrop targets the <dialog> itself, so native browser
   // popups (date pickers, selects, color pickers) that render outside the
-  // dialog's bounding rect.
-  const handleClick = (event: React.MouseEvent<HTMLDialogElement>) => {
-    if (event.target === event.currentTarget && allowBackdropClick) {
-      onOpenChange(false);
-    }
-  };
+  // dialog's rect never count. The press must start and end there.
+  const handleBackdropPress = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
+  const backdropPress = useBackdropPress(
+    handleBackdropPress,
+    allowBackdropClick,
+  );
 
   // The native `cancel` event is the browser's own close-watcher firing: an
   // Android back gesture, or a close request the stack never saw a press for.
@@ -854,8 +908,20 @@ export function Dialog({
       // written.
       {...layerClickBoundary({
         ...safeProps,
-        onClick: chainEventHandlers(handleClick, onClickProp),
+        onClick: chainEventHandlers(backdropPress.onClick, onClickProp),
       })}
+      onPointerDownCapture={chainEventHandlers(
+        backdropPress.onPointerDownCapture,
+        safeProps.onPointerDownCapture as PointerHandler | undefined,
+      )}
+      onPointerUpCapture={chainEventHandlers(
+        backdropPress.onPointerUpCapture,
+        safeProps.onPointerUpCapture as PointerHandler | undefined,
+      )}
+      onPointerCancelCapture={chainEventHandlers(
+        backdropPress.onPointerCancelCapture,
+        safeProps.onPointerCancelCapture as PointerHandler | undefined,
+      )}
       onCancel={handleCancel}
       aria-modal={isHydrating ? undefined : 'true'}
       // The default aria-labelledby (from a DialogHeader title) is set

package/src/Drawer/Drawer.tsx

@@ -78,9 +78,11 @@ import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
 import {useModalOutlet} from '../Layer/modalOutlet';
+import {useBackdropPress} from '../Layer/useBackdropPress';
 import {layerClickBoundary} from '../Layer/layerClickBoundary';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {composeEventHandlers, mergeProps, themeProps} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {container, overlayPaddingReset} from '../Layout';
 import {
   containerPaddingBlockEndVarStyles,
@@ -92,6 +94,8 @@ import {
 import type {SpacingStep, SpacingToken} from '../Layout';
 import {useDrawerDialogPresence} from './useDrawerDialogPresence';
 
+type PointerHandler = (event: React.PointerEvent<HTMLDialogElement>) => void;
+
 // =============================================================================
 // Styles
 // =============================================================================
@@ -218,8 +222,8 @@ const styles = stylex.create({
   // Scrim via the browser's ::backdrop pseudo-element (top layer).
   scrim: {
     '::backdrop': {
+      // No backdrop-filter: a full-viewport blur is costly to repaint.
       backgroundColor: colorVars['--color-overlay'],
-      backdropFilter: 'blur(2px)',
       opacity: 0,
       transitionProperty: 'opacity',
       transitionDuration: durationVars['--duration-medium'],
@@ -543,15 +547,14 @@ export function Drawer({
     [allowEscape, handleDismiss, shouldDismissOnCloseRequest],
   );
 
-  // Clicks on the ::backdrop target the <dialog> element itself; clicks on
-  // drawer content always target a child (the content area fills the panel).
-  const handleClick = useCallback(
-    (event: React.MouseEvent<HTMLDialogElement>) => {
-      if (event.target === event.currentTarget && hasScrim && allowScrimClick) {
-        onOpenChange(false);
-      }
-    },
-    [allowScrimClick, hasScrim, onOpenChange],
+  // A press on the ::backdrop targets the <dialog> itself (the content area
+  // fills the panel). The press must start and end there.
+  const handleScrimPress = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
+  const scrimPress = useBackdropPress(
+    handleScrimPress,
+    hasScrim && allowScrimClick,
   );
 
   const widthValue = typeof width === 'number' ? `${width}px` : width;
@@ -612,8 +615,22 @@ export function Drawer({
       // written.
       {...layerClickBoundary({
         ...safeProps,
-        onClick: composeEventHandlers(onClickProp, handleClick),
+        onClick: composeEventHandlers(onClickProp, scrimPress.onClick),
       })}
+      // The hook records where the press started first. The caller's capture
+      // handler then runs, also when a child prevented default.
+      onPointerDownCapture={chainEventHandlers(
+        scrimPress.onPointerDownCapture,
+        safeProps.onPointerDownCapture as PointerHandler | undefined,
+      )}
+      onPointerUpCapture={chainEventHandlers(
+        scrimPress.onPointerUpCapture,
+        safeProps.onPointerUpCapture as PointerHandler | undefined,
+      )}
+      onPointerCancelCapture={chainEventHandlers(
+        scrimPress.onPointerCancelCapture,
+        safeProps.onPointerCancelCapture as PointerHandler | undefined,
+      )}
       onKeyDown={onKeyDownProp}
       onCancel={handleCancel}>
       <ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen && hasScrim}>

package/src/Drawer/useDrawerDialogPresence.ts

@@ -32,6 +32,8 @@ import {
   type SetStateAction,
 } from 'react';
 import {flushSync} from 'react-dom';
+import {notifyTopLayerEntry} from '../Layer/modalOutlet';
+import {runPopoverOperation} from '../Layer/popoverOperations';
 
 /** Slack past the computed transition before the backstop gives up waiting. */
 const EXIT_BACKSTOP_BUFFER_MS = 50;
@@ -70,7 +72,13 @@ function showDrawerHost(dialog: HTMLDialogElement, isModal: boolean): void {
   if (isModal) {
     dialog.showModal();
   } else if (typeof dialog.showPopover === 'function') {
-    dialog.showPopover();
+    // The dialog's show focuses its first control. A tooltip on that control
+    // then asks to show. The browser refuses a show inside another show.
+    // Counting this show makes the tooltip wait until it ends.
+    runPopoverOperation(dialog.ownerDocument, () => dialog.showPopover());
+    // The drawer is now the newest top-layer entry: global hosts shown before
+    // it (the toast viewport) re-enter above it, as they do above a modal.
+    notifyTopLayerEntry();
   } else {
     // Reduced fallback for browsers below the Popover API support floor.
     dialog.show();

package/src/DropdownMenu/DropdownMenu.tsx

@@ -533,6 +533,20 @@ function holdInvokerThroughPress(
   doc.addEventListener('pointercancel', onPressEnd, true);
 }
 
+/**
+ * The name of a menu opened from a custom trigger: the caller's `aria-label`
+ * when it is a non-empty string, else the trigger's own accessible name. The
+ * popover and the bottom sheet both name the menu through this.
+ */
+function resolveCustomTriggerMenuName(
+  callerLabel: unknown,
+  triggerName: string | undefined,
+): string | undefined {
+  return typeof callerLabel === 'string' && callerLabel.trim() !== ''
+    ? callerLabel
+    : triggerName;
+}
+
 function DropdownMenuBottomSheet({
   button: buttonFromProps,
   renderTrigger,
@@ -596,11 +610,22 @@ function DropdownMenuBottomSheet({
   useEffect(() => {
     void preloadMenuBottomSheetActionList();
   }, []);
+  // The control's name is only readable from the DOM once it is rendered.
+  const [triggerName, setTriggerName] = useState<string | undefined>(undefined);
+  useIsomorphicLayoutEffect(() => {
+    if (renderTrigger != null && isOpen) {
+      setTriggerName(readAccessibleName(buttonRef.current));
+    }
+  }, [renderTrigger, isOpen]);
+  const rootTitle =
+    (renderTrigger != null
+      ? resolveCustomTriggerMenuName(rest['aria-label'], triggerName)
+      : undefined) ?? button.label;
   const currentSubmenu = submenuPath.at(-1);
   const currentItems = currentSubmenu?.items ?? items;
-  const currentTitle = currentSubmenu?.label ?? button.label;
+  const currentTitle = currentSubmenu?.label ?? rootTitle;
   const sheetLabel =
-    typeof currentTitle === 'string' ? currentTitle : button.label;
+    typeof currentTitle === 'string' ? currentTitle : rootTitle;
 
   const setOpen = useCallback(
     (nextIsOpen: boolean) => {
@@ -1040,12 +1065,9 @@ function DropdownMenuPopover({
   // The design system's button names the menu by its label. A custom trigger
   // names it by reference (or the caller's `aria-label` does), so that name
   // is read off the control as the menu opens.
-  const callerMenuLabel = rest['aria-label'];
   const menuLabel =
     renderTrigger != null
-      ? typeof callerMenuLabel === 'string' && callerMenuLabel.trim() !== ''
-        ? callerMenuLabel
-        : triggerName
+      ? resolveCustomTriggerMenuName(rest['aria-label'], triggerName)
       : typeof button.label === 'string'
         ? button.label
         : undefined;

package/src/Field/Field.tsx

@@ -25,11 +25,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 import type {FieldStatusPlacement} from './fieldStatusPlacement';
 

package/src/Field/PanelSearchInput.tsx

@@ -58,6 +58,7 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {textEntryTraitAttributes} from './textEntryTraits';
+import {inputWrapperStyles} from './inputStyles.stylex';
 
 const styles = stylex.create({
   // Gutter only. Matches the option list's own padding so the field below
@@ -185,6 +186,14 @@ export interface PanelSearchInputProps extends Omit<
    * the field to the same height as its rows.
    */
   fieldXstyle?: StyleXStyles;
+  /**
+   * Draw the field as the shared input box — the input border, accent while
+   * focused, surface and radius — instead of the borderless panel row. A
+   * touch sheet is a full-width surface, not a bordered panel, so its field
+   * reads as a form input.
+   * @default false
+   */
+  hasInputBox?: boolean;
 }
 
 /**
@@ -208,6 +217,7 @@ export function PanelSearchInput({
   onBlur,
   onContainerKeyDown,
   fieldXstyle,
+  hasInputBox = false,
   xstyle,
   className,
   style,
@@ -268,6 +278,7 @@ export function PanelSearchInput({
         {...stylex.props(
           styles.field,
           isKeyboardFocus && styles.fieldKeyboardFocus,
+          hasInputBox && inputWrapperStyles.base,
           fieldXstyle,
         )}>
         <Icon icon="search" size="sm" color="secondary" xstyle={styles.icon} />

package/src/HoverCard/HoverCard.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
+import {
+  useCallback,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {observeMutations} from '../utils/sharedMutationObserver';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -303,6 +310,28 @@ export function HoverCard({
     onHide: handleHide,
   });
 
+  // The wrapper's first element is the trigger, and it can be replaced after
+  // mount: by new children, or by a child component that swaps its own root
+  // without a render here. Syncs with the DOM: on a replacement the wiring
+  // below re-runs, so the old element is released before the new one is wired.
+  const [triggerReplacements, setTriggerReplacements] = useState(0);
+  const observedTriggerRef = useRef<Element | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (textOnly || wrapper == null) {
+      return;
+    }
+    observedTriggerRef.current = wrapper.firstElementChild;
+    return observeMutations(wrapper, {childList: true}, () => {
+      const trigger = wrapper.firstElementChild;
+      if (trigger === observedTriggerRef.current) {
+        return;
+      }
+      observedTriggerRef.current = trigger;
+      setTriggerReplacements(count => count + 1);
+    });
+  }, [textOnly]);
+
   // For element children with display:contents, attach ref to first child
   useIsomorphicLayoutEffect(() => {
     if (textOnly) {
@@ -407,6 +436,7 @@ export function HoverCard({
     hoverCard.id,
     hoverCard.isOpen,
     hoverCard.describedBy,
+    triggerReplacements,
   ]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX

package/src/Icon/Icon.doc.mjs

@@ -71,15 +71,16 @@ export const docs = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key such as `richtext:bold` names a glyph that one component or library registers, and a theme can replace it by key; a namespaced key that nothing registers renders nothing. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to Astryx icon color tokens.',
+      description:
+        'Color variant mapped to Astryx icon color tokens. Semantic values (primary through warning) follow the role, and inherit uses the surrounding text color. On the web, Icon also accepts the palette values blue, red, green, gray, cyan, teal, yellow, orange, pink, and purple, which pick a non-semantic hue.',
       default: "'inherit'",
     },
     {
@@ -107,6 +108,24 @@ export const docs = {
       description:
         "StyleX styles for customization (color, size, opacity). Folded into the icon's own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.",
     },
+    {
+      name: 'className',
+      type: 'string',
+      description:
+        'Class name added to the rendered glyph, beside the astryx-icon target class.',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        "Inline styles merged onto the rendered glyph after Icon's own size and color styles.",
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        'Ref to the rendered SVG element when icon is an icon component. A semantic or namespaced name renders inside an internal wrapper, and the ref is not attached.',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -207,15 +226,16 @@ export const docsZh = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。命名空间键（如 `richtext:bold`）指向某个组件或库注册的图标，主题可以按键替换它；没有注册的命名空间键不渲染任何内容。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
+      description:
+        '映射到 Astryx 图标颜色令牌的颜色变体。语义值（primary 到 warning）跟随角色，inherit 使用周围文字的颜色。在 Web 上，Icon 还接受调色板值 blue、red、green、gray、cyan、teal、yellow、orange、pink 和 purple，它们选择非语义色相。',
       default: "'inherit'",
     },
     {
@@ -243,6 +263,23 @@ export const docsZh = {
       description:
         '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
     },
+    {
+      name: 'className',
+      type: 'string',
+      description: '添加到渲染图标上的类名，与 astryx-icon 目标类名并列。',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        '合并到渲染图标上的内联样式，位于 Icon 自身的尺寸和颜色样式之后。',
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        'icon 为图标组件时，指向渲染的 SVG 元素的 ref。语义名称或命名空间名称在内部包装元素中渲染，不会附加 ref。',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -390,8 +427,9 @@ 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, upload, 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.',
+    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, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key (`richtext:bold`) names a glyph a component or library registers; an unregistered one renders nothing. For others, pass an SVG component.',
+    color:
+      'Color variant mapped to Astryx icon color tokens; inherit = surrounding text color. Web also accepts the non-semantic palette: blue, red, green, gray, cyan, teal, yellow, orange, pink, purple.',
     size: "xsm/sm/md/lg = 12/16/20/24px at a 16px root, scale w/ root font size; theme sets a size's glyph dimension via width + height (px or rem) on components.icon['size:sm'] etc. Explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     variant:
       "Requests the active theme's alternate artwork (e.g. 'filled'); names from augmentable IconVariantMap. Reaches the entry only if the active theme's iconVariants lists it (and an inherited entry's defining theme does too); else normal artwork. Ignored by a directly passed component; never in the DOM; no theming selector.",
@@ -399,5 +437,8 @@ export const docsDense = {
       '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:
       'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
+    className: 'Class added to the rendered glyph beside astryx-icon.',
+    style: "Inline styles merged after Icon's size and color styles.",
+    ref: 'Reaches the SVG only when icon is a component; a semantic or namespaced name renders in a wrapper and gets no ref.',
   },
 };

package/src/Icon/Icon.tsx

@@ -176,7 +176,11 @@ export interface IconProps extends Omit<
   SVGProps<SVGSVGElement>,
   'ref' | 'color'
 > {
-  /** Ref forwarded to the root element */
+  /**
+   * Ref to the rendered SVG element when `icon` is an icon component. A
+   * semantic or namespaced name renders inside an internal wrapper, and the
+   * ref is not attached.
+   */
   ref?: React.Ref<SVGSVGElement>;
   /**
    * Icon to render. Can be:
@@ -267,22 +271,26 @@ export interface IconProps extends Omit<
   xstyle?: StyleXStyles;
 }
 
+type IconA11yProps =
+  | {role: 'img'; 'aria-label': string; 'aria-hidden': undefined}
+  | {'aria-hidden': 'true'};
+
 /**
  * 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).
+ *   tree, so its accessible name would be ignored). Icon passes
+ *   `aria-hidden: undefined`. Many icon components, such as Heroicons, write
+ *   `aria-hidden="true"` unless a prop replaces it.
  * - 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: string | undefined,
-): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+function getIconA11yProps(label: string | undefined): IconA11yProps {
   return label != null && label !== ''
-    ? {role: 'img', 'aria-label': label}
+    ? {role: 'img', 'aria-label': label, 'aria-hidden': undefined}
     : {'aria-hidden': 'true'};
 }
 
@@ -392,7 +400,7 @@ function IconFromRegistry({
   color: IconColor;
   size: IconSize;
   variant: IconVariant | undefined;
-  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  a11yProps: IconA11yProps;
   className?: string;
   style?: React.CSSProperties;
   xstyle?: StyleXStyles;