@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/HoverCard/useHoverCard.tsx

@@ -119,6 +119,15 @@ export interface HoverCardOptions {
    */
   isEnabled?: boolean;
 
+  /**
+   * Accessible name for the hover card popup.
+   *
+   * When provided, the popup is exposed to assistive technology as a named
+   * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
+   * a group may validly be unnamed, an unnamed dialog may not.
+   */
+  label?: string;
+
   /**
    * Controlled open state. When provided, overrides hover/focus triggers:
    * - `true`: force-show the hover card (hover/focus hide is suppressed)
@@ -250,6 +259,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideDelay = 200,
     focusTrigger = 'auto',
     isEnabled = true,
+    label,
     isOpen,
     isDefaultOpen = false,
     onShow,
@@ -462,7 +472,11 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
-        role: 'dialog',
+        // A named dialog when a label is provided; otherwise a group. A group
+        // may validly be unnamed, an unnamed dialog may not — and hover cards
+        // are non-modal, so group is honest semantics without a name.
+        role: label ? 'dialog' : 'group',
+        'aria-label': label || undefined,
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
         // Render the layer as inline-safe phrasing markup so HoverCard stays
         // valid (and hydration-stable) inside inline contexts like a `<p>`.
@@ -516,7 +530,15 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         renderProps,
       );
     },
-    [layer, placement, alignment, clearTimeouts, scheduleHide, popoverXstyle],
+    [
+      layer,
+      placement,
+      alignment,
+      label,
+      clearTimeouts,
+      scheduleHide,
+      popoverXstyle,
+    ],
   );
 
   return {

package/src/Icon/Icon.doc.mjs

@@ -34,6 +34,11 @@ export const docs = {
       description: 'Icon size.',
       default: "'md'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons — one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
+    },
   ],
   theming: {
     targets: [
@@ -45,6 +50,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
+      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop — it sets role="img" + aria-label and unhides the icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
       { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
       { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
@@ -79,6 +85,11 @@ export const docsZh = {
       description: '图标尺寸。',
       default: "'md'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
+    },
   ],
   theming: {
     targets: [
@@ -123,5 +134,6 @@ export const docsDense = {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
+    label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
   },
 };

package/src/Icon/Icon.test.tsx

@@ -96,6 +96,52 @@ describe('Icon', () => {
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
+  it('sizes component-mode icons in rem so they scale with root font-size', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon={TestIcon}
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      unmount();
+    }
+  });
+
+  it('sizes registry (string-mode) icons in rem, including fontSize', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon="check"
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      // fontSize is expressed in rem so 1em-based registry icons scale too.
+      expect(style.fontSize).toBe(expected);
+      unmount();
+    }
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(<Icon icon={TestIcon} ref={ref} />);
@@ -137,4 +183,100 @@ describe('Icon', () => {
     expect(icon).toHaveAttribute('aria-label', 'Done');
     expect(icon).toHaveAttribute('aria-hidden', 'false');
   });
+
+  describe('label (accessible name)', () => {
+    it('makes a component-mode icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon={TestIcon} label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('makes a string-mode (registry) icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon="check" label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('keeps the decorative default when label is omitted (component mode)', () => {
+      render(<Icon icon={TestIcon} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('keeps the decorative default when label is omitted (string mode)', () => {
+      render(<Icon icon="check" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (component mode)', () => {
+      render(<Icon icon={TestIcon} label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (string mode)', () => {
+      render(<Icon icon="check" label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('lets an explicit aria-hidden win over label (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-hidden win over label (string mode)', () => {
+      render(
+        <Icon icon="check" label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-label override the label-derived name (component mode)', () => {
+      render(
+        <Icon
+          icon={TestIcon}
+          label="Close"
+          aria-label="Dismiss"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'aria-label',
+        'Dismiss',
+      );
+    });
+
+    it('lets an explicit role override the label-derived role (string mode)', () => {
+      render(
+        <Icon
+          icon="check"
+          label="Close"
+          role="presentation"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'role',
+        'presentation',
+      );
+    });
+  });
 });

package/src/Icon/Icon.tsx

@@ -111,51 +111,64 @@ const colorStyles = stylex.create({
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = stylex.create({
   xsm: {
-    width: 12,
-    height: 12,
+    width: '0.75rem',
+    height: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
+    width: '1rem',
+    height: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
+    width: '1.25rem',
+    height: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
+    width: '1.5rem',
+    height: '1.5rem',
   },
 });
 
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = stylex.create({
+  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
+     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
+     the 14px-anchored textSizeVars type scale. Values are rem so icons track
+     the root font-size. */
   xsm: {
-    width: 12,
-    height: 12,
-    fontSize: 12,
+    width: '0.75rem',
+    height: '0.75rem',
+    fontSize: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
-    fontSize: 16,
+    width: '1rem',
+    height: '1rem',
+    fontSize: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
-    fontSize: 20,
+    width: '1.25rem',
+    height: '1.25rem',
+    fontSize: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
-    fontSize: 24,
+    width: '1.5rem',
+    height: '1.5rem',
+    fontSize: '1.5rem',
   },
+  /* eslint-enable @astryx/no-hardcoded-styles */
 });
 
 // =============================================================================
@@ -194,13 +207,57 @@ export interface IconProps extends Omit<
   color?: IconColor;
   /**
    * The size of the icon.
-   * - 'xsm': 12px
-   * - 'sm': 16px
-   * - 'md': 20px
-   * - 'lg': 24px
+   * - 'xsm': 0.75rem (12px at a 16px root)
+   * - 'sm': 1rem (16px at a 16px root)
+   * - 'md': 1.25rem (20px at a 16px root)
+   * - 'lg': 1.5rem (24px at a 16px root)
    * @default 'md'
    */
   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;
+}
+
+/**
+ * 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: string | undefined,
+): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+  return label != null && label !== ''
+    ? {role: 'img', 'aria-label': label}
+    : {'aria-hidden': 'true'};
 }
 
 // =============================================================================
@@ -219,9 +276,14 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }: IconProps) {
+  // 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 (
@@ -229,6 +291,7 @@ export function Icon({
         name={icon}
         color={color}
         size={size}
+        a11yProps={a11yProps}
         spanProps={props}
       />
     );
@@ -239,7 +302,10 @@ export function Icon({
   return (
     <IconComponent
       ref={ref}
-      aria-hidden="true"
+      // 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}),
         stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
@@ -266,11 +332,13 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
+  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -281,11 +349,11 @@ function IconFromRegistry({
 
   return (
     <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"
+      // Derived a11y — decorative (aria-hidden) by default, or a meaningful
+      // image (role="img" + aria-label) when `label` is set. Placed BEFORE the
+      // prop spread so consumers can still override it with explicit
+      // aria-hidden/role/aria-label. This mirrors component-mode Icon.
+      {...a11yProps}
       {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
       {...mergeProps(
         themeProps('icon', {size, color}),

package/src/IconButton/IconButton.doc.mjs

@@ -36,6 +36,13 @@ export const docs = {
       description: 'Size variant.',
       default: "\'md\'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. The most common FAB shape is an icon-only button, so raise it with `low`/`med`/`high` for a floating action button. `none` is the default flat button.',
+      default: "'none'",
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -95,6 +102,7 @@ export const docsDense = {
     icon: 'icon element rendered inside button',
     variant: 'visual style variant',
     size: 'size variant',
+    elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
     isLoading: 'shows loading spinner + disables interaction',
     isDisabled: 'disables button',
     tooltip: 'tooltip text shown on hover',

package/src/IconButton/IconButton.test.tsx

@@ -17,10 +17,7 @@ import {IconButton} from './IconButton';
 describe('IconButton', () => {
   it('renders as an icon-only button with aria-label', () => {
     render(
-      <IconButton
-        label="Settings"
-        icon={<span data-testid="icon">⚙</span>}
-      />,
+      <IconButton label="Settings" icon={<span data-testid="icon">⚙</span>} />,
     );
     const button = screen.getByRole('button', {name: 'Settings'});
     expect(button).toHaveAttribute('aria-label', 'Settings');
@@ -29,10 +26,7 @@ describe('IconButton', () => {
 
   it('does not render label as visible text', () => {
     render(
-      <IconButton
-        label="Settings"
-        icon={<span data-testid="icon">⚙</span>}
-      />,
+      <IconButton label="Settings" icon={<span data-testid="icon">⚙</span>} />,
     );
     const button = screen.getByRole('button');
     // The label text should not appear as visible content
@@ -42,11 +36,7 @@ describe('IconButton', () => {
 
   it('forwards variant prop', () => {
     render(
-      <IconButton
-        label="Delete"
-        icon={<span>🗑</span>}
-        variant="destructive"
-      />,
+      <IconButton label="Delete" icon={<span>🗑</span>} variant="destructive" />,
     );
     expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
   });
@@ -60,11 +50,7 @@ describe('IconButton', () => {
     const user = userEvent.setup();
     const handleClick = vi.fn();
     render(
-      <IconButton
-        label="Close"
-        icon={<span>✕</span>}
-        onClick={handleClick}
-      />,
+      <IconButton label="Close" icon={<span>✕</span>} onClick={handleClick} />,
     );
 
     await user.click(screen.getByRole('button'));
@@ -105,4 +91,15 @@ describe('IconButton', () => {
   it('has displayName set', () => {
     expect(IconButton.displayName).toBe('IconButton');
   });
+
+  it('forwards the elevation prop through to the underlying button', () => {
+    const classFor = (elevation: 'none' | 'med') => {
+      const {container} = render(
+        <IconButton label="Add" icon={<span>+</span>} elevation={elevation} />,
+      );
+      return container.querySelector('button')!.className;
+    };
+    // A raised FAB must render differently from the default flat icon button.
+    expect(classFor('med')).not.toBe(classFor('none'));
+  });
 });

package/src/Item/Item.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
       props: [
         {name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
         {name: 'marker', type: 'ReactNode', description: 'Marker rendered before startContent as a direct flex child. Use for list bullets/counters that need custom baseline alignment.'},
-        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
+        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'sm'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
         {name: 'description', type: 'ReactNode', description: 'Secondary text: subtitle, description, or supporting info.'},
         {name: 'endContent', type: 'ReactNode', description: 'Content rendered after the label/description area, such as badges, metadata, timestamps, or action buttons.', slotElements: [{__element: 'Badge', props: {label: 3}}, {__element: 'Text', props: {color: 'secondary'}, children: '2h ago'}]},
         {name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},

package/src/Layer/useLayer.tsx

@@ -100,6 +100,12 @@ export interface ContextRenderProps {
    * non-hashed selector for the layer.
    */
   role?: string;
+  /**
+   * Accessible name applied to the popover container via `aria-label`.
+   * Pair with `role` so layers with a named role (e.g. `'dialog'`) expose a
+   * proper name to assistive technology.
+   */
+  'aria-label'?: string;
   /**
    * StyleX styles for the popover container.
    */
@@ -525,6 +531,7 @@ export function useLayer(
         alignment = 'center',
         positioning = 'anchor',
         role,
+        'aria-label': ariaLabel,
         xstyle,
         className: extraClassName,
         style: extraStyle,
@@ -561,6 +568,7 @@ export function useLayer(
           ref={popoverRefCallback}
           id={id}
           role={role}
+          aria-label={ariaLabel}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
           style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}

package/src/MobileNav/MobileNav.tsx

@@ -29,6 +29,7 @@
 import {
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -295,6 +296,10 @@ export function MobileNav({
   // Read from AppShell context as fallback
   const appShellMobile = useAppShellMobile();
   const isOpen = isOpenProp ?? appShellMobile.isMobileNavOpen;
+  // Share the id from AppShell context so the toggle's aria-controls resolves to
+  // this drawer; fall back to a locally generated id when used standalone.
+  const fallbackId = useId();
+  const dialogId = appShellMobile.mobileNavId || fallbackId;
   const onOpenChange = useMemo(
     () =>
       onOpenChangeProp ??
@@ -411,6 +416,7 @@ export function MobileNav({
   return (
     <dialog
       ref={mergeRefs(ref, dialogRef)}
+      id={dialogId}
       {...mergeProps(
         themeProps('mobile-nav', {side: resolvedSide}),
         stylex.props(
@@ -425,7 +431,12 @@ export function MobileNav({
       )}
       {...rest}
       data-testid={testId}
-      aria-label={label ?? (typeof header === 'string' ? header : t('@astryx.mobileNav.navigation'))}
+      aria-label={
+        label ??
+        (typeof header === 'string'
+          ? header
+          : t('@astryx.mobileNav.navigation'))
+      }
       onClick={composeEventHandlers(onClickProp, handleDialogClick)}
       onCancel={handleCancel}>
       {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}