@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Tokenizer/Tokenizer.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Tokenizer.tsx
- * @input Uses React, BaseTypeahead, Field, Token
+ * @input Uses React, BaseTypeahead, Field, Token, useAnnounce
  * @output Exports Tokenizer multi-select typeahead component
  * @position Composed component; forwards DOM ref and exposes focus control via
  *   handleRef
@@ -37,12 +37,14 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {renderIconSlot, type IconType} from '../Icon';
 import {OverflowList} from '../OverflowList';
 import {useLayer} from '../Layer/useLayer';
 import {useTooltip} from '../Tooltip';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {
   colorVars,
   spacingVars,
@@ -110,6 +112,13 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -369,6 +378,7 @@ export function Tokenizer<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -560,6 +570,12 @@ export function Tokenizer<T extends SearchableItem>({
     [],
   );
 
+  // Announce token add/remove politely via the persistent live region.
+  // Tokens previously appeared and disappeared silently — Backspace on an
+  // empty input removes the trailing token, and the per-token remove buttons
+  // gave no audible feedback either.
+  const announce = useAnnounce();
+
   // Handle adding an item — detect creatable synthetic items
   const handleAdd = useCallback(
     (item: T | null) => {
@@ -584,6 +600,7 @@ export function Tokenizer<T extends SearchableItem>({
         const realItem = base as T;
         const newItems = [...value, realItem];
         onChange(newItems, {item: realItem, type: 'create'});
+        announce(`Added ${createdValue}`);
         return;
       }
 
@@ -592,18 +609,22 @@ export function Tokenizer<T extends SearchableItem>({
       }
       const newItems = [...value, item];
       onChange(newItems, {item, type: 'add'});
+      announce(`Added ${item.label}`);
     },
-    [value, onChange, isAtMax, selectedIds, hasCreate],
+    [value, onChange, isAtMax, selectedIds, hasCreate, announce],
   );
 
-  // Handle removing an item
+  // Handle removing an item. Single removal path: both Backspace on an empty
+  // input and the per-token remove buttons route through here, so the
+  // announcement covers both.
   const handleRemove = useCallback(
     (item: T) => {
       const newItems = value.filter(v => v.id !== item.id);
       onChange(newItems, {item, type: 'remove'});
+      announce(`Removed ${item.label}`);
       inputRef.current?.focus();
     },
-    [value, onChange],
+    [value, onChange, announce],
   );
 
   // Handle clearing all items
@@ -718,7 +739,7 @@ export function Tokenizer<T extends SearchableItem>({
           isTruncated && styles.truncatedWrapper,
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
-          status && inputStatusHoverShadowStyles[status.type],
+          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
         ),
       )}>
@@ -816,7 +837,9 @@ export function Tokenizer<T extends SearchableItem>({
               isTruncated && styles.truncatedWrapper,
               isDisabled && inputWrapperStyles.disabled,
               status && inputStatusBorderStyles[status.type],
-              status && inputStatusHoverShadowStyles[status.type],
+              status &&
+                !isDisabled &&
+                inputStatusHoverShadowStyles[status.type],
               status && inputStatusFocusWithinStyles[status.type],
             ),
           )}>
@@ -879,6 +902,7 @@ export function Tokenizer<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}

package/src/Tooltip/Tooltip.test.tsx

@@ -221,4 +221,50 @@ describe('Tooltip', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
     });
   });
+
+  describe('press-to-dismiss', () => {
+    it('hides the tooltip when the trigger is pressed', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Copy link" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.pointerDown(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('does not press-dismiss a controlled tooltip', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip
+          content="Controlled"
+          isOpen
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      fireEvent.pointerDown(trigger);
+      // Give any (incorrect) async hide a chance to run.
+      await new Promise(r => setTimeout(r, 20));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+  });
 });

package/src/Tooltip/useTooltip.tsx

@@ -366,6 +366,19 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     scheduleHide();
   }, [scheduleHide]);
 
+  // Pressing the trigger hides its own tooltip: once the control is activated
+  // the hint has served its purpose, and a tooltip lingering over a
+  // just-pressed control reads as stale. Fires on pointerdown so it feels
+  // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
+  // is owned by the consumer. `layer.hide()` self-guards when already closed.
+  const handlePointerDown = useCallback(() => {
+    if (isOpen !== undefined) {
+      return;
+    }
+    clearTimeouts();
+    layer.hide();
+  }, [isOpen, clearTimeouts, layer]);
+
   // Interaction ref that handles event listeners only
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
@@ -375,12 +388,18 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
         triggerRef.current.removeEventListener('focusin', handleFocusIn);
         triggerRef.current.removeEventListener('focusout', handleFocusOut);
+        triggerRef.current.removeEventListener(
+          'pointerdown',
+          handlePointerDown,
+        );
       }
 
       if (el) {
         // Attach hover listeners
         el.addEventListener('mouseenter', handleMouseEnter);
         el.addEventListener('mouseleave', handleMouseLeave);
+        // Press-to-dismiss: activating the trigger hides its own tooltip.
+        el.addEventListener('pointerdown', handlePointerDown);
 
         // Attach focus listeners based on focusTrigger option
         const shouldAttachFocus =
@@ -401,6 +420,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       handleMouseLeave,
       handleFocusIn,
       handleFocusOut,
+      handlePointerDown,
     ],
   );
 

package/src/TopNav/TopNav.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNav} from './TopNav';
 import {TopNavRenderContext} from './TopNavRenderContext';
@@ -297,6 +297,85 @@ describe('TopNavHeading', () => {
     render(<TopNavHeading heading="Test" ref={ref} />);
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
   });
+
+  // ===========================================================================
+  // Menu popover semantics — the popup must not be announced as a modal
+  // dialog, and role="menu" must be scoped to the actual menu items so the
+  // heading button is not an invalid child of the menu.
+  // ===========================================================================
+
+  // The popover layer keeps `popover` content display:none in jsdom even
+  // when open, hiding it from role queries — so these tests assert the
+  // popup's ARIA semantics at the DOM level instead.
+  describe('menu popover semantics', () => {
+    const menuItems = (
+      <>
+        <div role="menuitem">Alpha</div>
+        <div role="menuitem">Beta</div>
+      </>
+    );
+
+    it('does not wrap the heading menu popup in a modal dialog', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+    });
+
+    it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'My App');
+      const children = Array.from(menu!.children);
+      expect(children.length).toBeGreaterThan(0);
+      for (const child of children) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+
+    it('keeps the popup heading button outside the menu and closes on click', async () => {
+      const user = userEvent.setup();
+      render(<TopNavHeading heading="My App" menu={menuItems} />);
+      const trigger = screen.getByRole('button', {name: 'Open menu'});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      // The heading replica button in the popup is a sibling of the menu,
+      // not an invalid menu child.
+      const headingButton = Array.from(
+        document.querySelectorAll('button'),
+      ).find(b => b !== trigger && b.textContent?.includes('My App'));
+      expect(headingButton).toBeDefined();
+      expect(menu!.contains(headingButton!)).toBe(false);
+      // Clicking it still closes the popup.
+      fireEvent.click(headingButton!);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+      const user = userEvent.setup();
+      render(
+        <TopNavHeading
+          heading="Product"
+          headingHref="/product"
+          menu={menuItems}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      expect(document.querySelector('[role="dialog"]')).toBeNull();
+      const menu = document.querySelector('[role="menu"]');
+      expect(menu).not.toBeNull();
+      expect(menu).toHaveAttribute('aria-label', 'Product');
+      for (const child of Array.from(menu!.children)) {
+        expect(child).toHaveAttribute('role', 'menuitem');
+      }
+    });
+  });
 });
 
 describe('NavIcon', () => {
@@ -444,4 +523,49 @@ describe('TopNavItem', () => {
       expect(card).toHaveAttribute('aria-label', 'Featured');
     });
   });
+
+  describe('TopNavMegaMenuFeaturedCard image alt handling', () => {
+    it('marks the image as explicitly decorative when imageAlt is omitted', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          data-testid="featured-card"
+        />,
+      );
+      const img = screen.getByTestId('featured-card').querySelector('img');
+      expect(img).toHaveAttribute('alt', '');
+      expect(img).toHaveAttribute('role', 'presentation');
+      expect(img).toHaveAttribute('aria-hidden', 'true');
+      // The image must not be exposed to assistive technology as a nameless img.
+      expect(screen.queryByRole('img')).toBeNull();
+    });
+
+    it('exposes the image with normal img semantics when imageAlt is provided', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          imageAlt="Team collaboration"
+        />,
+      );
+      const img = screen.getByRole('img', {name: 'Team collaboration'});
+      expect(img).not.toHaveAttribute('role');
+      expect(img).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('keeps title and link semantics unchanged with a decorative image', () => {
+      render(
+        <TopNavMegaMenuFeaturedCard
+          title="What's new"
+          image="/promo.jpg"
+          linkLabel="Read the announcement"
+          linkHref="/blog/v4"
+        />,
+      );
+      expect(screen.getByText("What's new")).toBeInTheDocument();
+      const link = screen.getByRole('link', {name: /Read the announcement/});
+      expect(link).toHaveAttribute('href', '/blog/v4');
+    });
+  });
 });

package/src/TopNav/TopNavHeading.tsx

@@ -332,6 +332,10 @@ export function TopNavHeading({
 
   const popover = usePopover({
     dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
+    // The popup exposes its own role="menu" semantics; a role="dialog"
+    // aria-modal wrapper would announce "dialog, Navigation menu" around a
+    // menu (the anti-pattern removed in a478a3dcf).
+    role: 'none',
     hasCloseButton: false,
   });
 
@@ -511,13 +515,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',
@@ -575,13 +585,19 @@ export function TopNavHeading({
         {popover.render(
           <div
             ref={menuRef}
-            role="menu"
             {...stylex.props(styles.popoverContent)}
             {...contentProps}>
             {popoverHeadingContent}
-            <NavHeadingCloseContext value={closeMenuCtx}>
-              {menu}
-            </NavHeadingCloseContext>
+            {/* The menu role is scoped to the actual menu items so the
+                heading button above stays a valid sibling, not an invalid
+                child of a role="menu" element. */}
+            <div
+              role="menu"
+              aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+              <NavHeadingCloseContext value={closeMenuCtx}>
+                {menu}
+              </NavHeadingCloseContext>
+            </div>
           </div>,
           {
             placement: 'below',

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNavMegaMenu} from './TopNavMegaMenu';
@@ -75,6 +75,154 @@ describe('TopNavMegaMenu — default mode', () => {
   });
 });
 
+// =============================================================================
+// Popup semantics (default mode)
+// =============================================================================
+
+describe('TopNavMegaMenu — popup semantics', () => {
+  // Mock the Popover API (not implemented in jsdom).
+  const originalMatches = HTMLElement.prototype.matches;
+
+  beforeAll(() => {
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('popover-open', '');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'open'});
+      this.dispatchEvent(event);
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('popover-open');
+      const event = new Event('toggle', {bubbles: false});
+      Object.defineProperty(event, 'newState', {value: 'closed'});
+      this.dispatchEvent(event);
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = function (
+      selector: string,
+    ): boolean {
+      if (selector === ':popover-open') {
+        return this.hasAttribute('popover-open');
+      }
+      return originalMatches.call(this, selector);
+    };
+  });
+
+  afterAll(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (HTMLElement.prototype as any).matches = originalMatches;
+  });
+
+  it('trigger aria-controls resolves to the popup element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    // aria-controls must be present and point at the real popup element.
+    const controlsId = trigger.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const popup = document.getElementById(controlsId as string);
+    expect(popup).not.toBeNull();
+
+    await user.click(trigger);
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    // The referenced element is the popup that contains the panel content.
+    expect(popup).toContainElement(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    );
+  });
+
+  it('does not wrap the panel in a role="dialog" aria-modal element', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Focus stays on the trigger while the panel is open, so a modal dialog
+    // wrapper would tell assistive tech the focused control is inert.
+    expect(
+      screen.queryByRole('dialog', {hidden: true}),
+    ).not.toBeInTheDocument();
+    expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+  });
+
+  it('does not expose role="menu" — a link grid is not an ARIA menu', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    // Per the WAI-ARIA APG, mega menu panels of navigation links must not use
+    // the menu role (reserved for action menus with menuitem children).
+    expect(screen.queryByRole('menu', {hidden: true})).not.toBeInTheDocument();
+    expect(screen.queryAllByRole('menuitem', {hidden: true})).toHaveLength(0);
+  });
+
+  it('exposes the panel as a labeled group', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    expect(
+      screen.getByRole('group', {name: 'Products', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps item links with accessible names inside the panel', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavMegaMenu
+        label="Products"
+        items={
+          <>
+            <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+            <TopNavMegaMenuItem title="Reports" href="/reports" />
+          </>
+        }
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Products'}));
+
+    const analytics = screen.getByRole('link', {
+      name: /Analytics/,
+      hidden: true,
+    });
+    expect(analytics).toHaveAttribute('href', '/analytics');
+    expect(
+      screen.getByRole('link', {name: /Reports/, hidden: true}),
+    ).toHaveAttribute('href', '/reports');
+  });
+});
+
 // =============================================================================
 // Mobile-bar mode — should be hidden
 // =============================================================================

package/src/TopNav/TopNavMegaMenu.tsx

@@ -354,7 +354,11 @@ function DefaultMegaMenu({
   }, [onOpenChange]);
 
   const popover = usePopover({
-    dialogLabel: label,
+    // role: 'none' — the panel exposes its own role="group" labeled by
+    // `label`. Focus stays on the trigger while the panel is open, so a
+    // role="dialog" aria-modal="true" wrapper would announce an unnamed
+    // modal dialog around a grid of links.
+    role: 'none',
     // hasSurface: false — mega menu provides its own surface (panelContainer)
     // with border-top and custom overflow. Animation is applied via the
     // render() call's xstyle prop (panelAnimation), not the hook options.
@@ -434,8 +438,7 @@ function DefaultMegaMenu({
       <button
         ref={mergeRefs(triggerButtonRef, ref)}
         type="button"
-        aria-haspopup="true"
-        aria-expanded={popover.isOpen}
+        {...popover.triggerProps}
         onClick={handleClick}
         onMouseEnter={handleMouseEnter}
         onMouseLeave={handleMouseLeave}
@@ -454,7 +457,10 @@ function DefaultMegaMenu({
       </button>
       {popover.render(
         <div
-          role="menu"
+          // role="group" — a mega menu is a browsing grid of links, not an
+          // ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is
+          // for action menus; link mega menus are the documented anti-case).
+          role="group"
           aria-label={label}
           onMouseEnter={handleMouseEnter}
           onMouseLeave={handleMouseLeave}

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: 'Alt text for the image.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden), usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
     },
     {
       name: 'linkLabel',
@@ -71,7 +71,7 @@ export const docsZh = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: '图片的替代文本。',
+      description: '图片的替代文本。省略时图片会被显式标记为装饰性（alt=""、role="presentation"、aria-hidden）——由于卡片已有可见标题，这通常是正确的。仅当图片传达标题和描述之外的信息时才提供。',
     },
     {
       name: 'linkLabel',
@@ -99,7 +99,7 @@ export const docsDense = {
     title: 'Card title.',
     description: 'Description below title.',
     image: 'Image URL above body.',
-    imageAlt: 'Image alt text.',
+    imageAlt: 'Image alt text. Omitted → explicitly decorative (hidden from screen readers); usually correct since card has visible title.',
     linkLabel: 'CTA link text.',
     linkHref: 'CTA link URL.',
     children: 'Custom content below standard body.',

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -84,7 +84,15 @@ export interface TopNavMegaMenuFeaturedCardProps extends BaseProps<HTMLDivElemen
   description?: string;
   /** Optional image URL displayed above the body. */
   image?: string;
-  /** Alt text for the image. */
+  /**
+   * Alt text for the image.
+   *
+   * When omitted, the image is explicitly decorative (`alt=""` +
+   * `role="presentation"` + `aria-hidden`, matching Avatar) and hidden from
+   * assistive technology. Since the card already has a visible `title`, a
+   * decorative image is usually correct; pass `imageAlt` only when the image
+   * conveys information beyond the title and description.
+   */
   imageAlt?: string;
   /** CTA link text. */
   linkLabel?: string;
@@ -149,7 +157,16 @@ export function TopNavMegaMenuFeaturedCard({
       )}
       {...rest}>
       {image && (
-        <img src={image} alt={imageAlt ?? ''} {...stylex.props(styles.image)} />
+        // Without `imageAlt`, the image is explicitly decorative rather than
+        // silently empty-alt, matching Avatar's handling of unnamed images.
+        // Usually correct here: the card already has a visible title.
+        <img
+          src={image}
+          alt={imageAlt ?? ''}
+          role={imageAlt ? undefined : 'presentation'}
+          aria-hidden={imageAlt ? undefined : true}
+          {...stylex.props(styles.image)}
+        />
       )}
       <div {...stylex.props(styles.body)}>
         <span {...stylex.props(styles.title)}>{title}</span>