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

package/src/HoverCard/HoverCard.tsx

@@ -96,6 +96,15 @@ export interface HoverCardProps extends Pick<
    */
   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;
+
   /**
    * Callback fired when hover card visibility changes.
    * Called with `true` when shown and `false` when hidden.
@@ -166,6 +175,7 @@ export function HoverCard({
   hideDelay = 200,
   focusTrigger = 'auto',
   isEnabled = true,
+  label,
   onOpenChange,
   hasHoverIndication = 'auto',
   isOpen,
@@ -197,6 +207,7 @@ export function HoverCard({
     hideDelay,
     focusTrigger,
     isEnabled,
+    label,
     isOpen,
     isDefaultOpen,
     onShow: handleShow,

package/src/HoverCard/useHoverCard.doc.mjs

@@ -13,6 +13,7 @@ export const docs = {
     {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
     {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
     {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
+    {name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},
     {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
     {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the hover card should be shown on mount.', default: 'false'},
     {name: 'onShow', type: '() => void', description: 'Callback fired when the hover card becomes visible.'},
@@ -52,6 +53,7 @@ export const docsDense = {
     hideDelay: 'hide delay after mouse/focus leave in ms.',
     focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
     isEnabled: 'whether hover/focus triggers are enabled.',
+    label: 'accessible name for popup. with label: named role="dialog"; without: role="group".',
     isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',
     onShow: 'fires when hover card becomes visible.',

package/src/HoverCard/useHoverCard.tsx

@@ -34,7 +34,6 @@ import {
   radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -119,6 +118,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 +258,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideDelay = 200,
     focusTrigger = 'auto',
     isEnabled = true,
+    label,
     isOpen,
     isDefaultOpen = false,
     onShow,
@@ -459,11 +468,28 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       props?: Omit<ContextRenderProps, 'positioning'>,
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
+      const themeClassName = themeProps('hovercard').className;
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
-        role: 'dialog',
-        xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // 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,
+        // Consumer surface style props land on the layer container — the
+        // themed surface (bg/radius/shadow) where the theme class lives — so
+        // customizing the card targets the same element as the theme. The inner
+        // span keeps `styles.content` for padding.
+        xstyle: [
+          popoverXstyle,
+          layerAnimations[renderPlacement],
+          props?.xstyle,
+        ],
+        className: props?.className
+          ? `${themeClassName} ${props.className}`
+          : themeClassName,
+        style: props?.style,
         // Render the layer as inline-safe phrasing markup so HoverCard stays
         // valid (and hydration-stable) inside inline contexts like a `<p>`.
         as: 'span' as const,
@@ -471,7 +497,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       return layer.render(
         <span
-          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
+          {...stylex.props(styles.content)}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();
@@ -516,7 +542,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

@@ -37,7 +37,13 @@ export const docs = {
     {
       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.',
+      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.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      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={{}}.',
     },
   ],
   theming: {
@@ -50,7 +56,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: '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.' },
@@ -90,6 +96,12 @@ export const docsZh = {
       type: 'string',
       description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
   ],
   theming: {
     targets: [
@@ -121,6 +133,7 @@ export const docsDense = {
     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), set an accessible name via `label`: sets role="img" + aria-label, unhides 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.' },
@@ -135,5 +148,6 @@ export const docsDense = {
     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.',
+    xstyle: 'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
   },
 };

package/src/Icon/Icon.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {Icon} from './Icon';
 
@@ -279,4 +280,92 @@ describe('Icon', () => {
       );
     });
   });
+
+  describe('styling prop handling', () => {
+    it('composes a consumer className with the internal classes (string mode)', () => {
+      render(
+        <Icon icon="check" className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      // Consumer className must survive alongside the stable astryx-icon class
+      // and the StyleX classes — previously it was clobbered by the later
+      // internal spread.
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+      // At least one StyleX-generated class is still present.
+      expect(icon.className.split(' ').length).toBeGreaterThan(2);
+    });
+
+    it('forwards a consumer className in component (SVG) mode', () => {
+      render(
+        <Icon icon={TestIcon} className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+    });
+
+    it('merges a consumer style onto the rendered element (string mode)', () => {
+      render(<Icon icon="check" style={{opacity: 0.5}} data-testid="icon" />);
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('merges a consumer style onto the rendered element (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} style={{opacity: 0.5}} data-testid="icon" />,
+      );
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('applies xstyle to the rendered element (string mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(<Icon icon="check" xstyle={overrides.root} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      // xstyle is folded into stylex.props, so it contributes a StyleX class
+      // (and, in jsdom's stylex runtime, an inline style) alongside the base
+      // color/size classes rather than clobbering them.
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('applies xstyle to the rendered element (component mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(
+        <Icon icon={TestIcon} xstyle={overrides.root} data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (string mode)', () => {
+      const {container} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // Default output is identical to itself — the styling-prop handling adds
+      // nothing (no extra class, no inline style) unless a prop is passed.
+      expect(icon.className).toBe(refIcon.className);
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (component mode)', () => {
+      const {container} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // SVGElement.className is an SVGAnimatedString, so compare the class
+      // attribute string rather than the property object.
+      expect(icon.getAttribute('class')).toBe(refIcon.getAttribute('class'));
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+  });
 });

package/src/Icon/Icon.tsx

@@ -24,6 +24,7 @@
 
 import React, {type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {getIcon} from './globalIconRegistry';
 import type {IconName} from './globalIconRegistry';
@@ -229,16 +230,34 @@ export interface IconProps extends Omit<
    * Don't set `label` when an interactive parent (Button, IconButton, link)
    * already names the control — that produces a duplicate announcement.
    *
+   * Meaningful, standalone icon: give it a label.
+   *
    * @example
    * ```
-   * // Meaningful, standalone icon
    * <Icon icon="success" label="Completed" />
+   * ```
+   *
+   * Decorative icon (the default): omit label.
    *
-   * // Decorative icon (default) — omit label
+   * @example
+   * ```
    * <Icon icon="search" />
    * ```
    */
   label?: string;
+  /**
+   * StyleX styles created via `stylex.create()`. Folded into the icon's own
+   * `stylex.props()` call (as the last argument) so it merges with the base
+   * color/size styles for optimal deduplication, matching how other Astryx
+   * components accept `xstyle`.
+   *
+   * @example
+   * ```
+   * const overrides = stylex.create({ root: { opacity: 0.5 } });
+   * <Icon icon="search" xstyle={overrides.root} />
+   * ```
+   */
+  xstyle?: StyleXStyles;
 }
 
 /**
@@ -278,6 +297,9 @@ export function Icon({
   size = 'md',
   label,
   ref,
+  className,
+  style,
+  xstyle,
   ...props
 }: IconProps) {
   // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
@@ -292,6 +314,9 @@ export function Icon({
         color={color}
         size={size}
         a11yProps={a11yProps}
+        className={className}
+        style={style}
+        xstyle={xstyle}
         spanProps={props}
       />
     );
@@ -306,9 +331,16 @@ export function Icon({
       // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
       // consumer still wins as an escape hatch.
       {...a11yProps}
+      // The styling props (className, style, xstyle) are handled here so they
+      // COMPOSE with the internal classes/styles instead of clobbering them:
+      // xstyle folds into stylex.props, and className/style merge via
+      // mergeProps. The remaining rest props keep their prior last-spread
+      // precedence as escape hatches.
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
+        stylex.props(styles.root, colorStyles[color], sizeStyles[size], xstyle),
+        className ?? undefined,
+        style,
       )}
       {...props}
     />
@@ -333,12 +365,18 @@ function IconFromRegistry({
   color,
   size,
   a11yProps,
+  className,
+  style,
+  xstyle,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
   a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  className?: string;
+  style?: React.CSSProperties;
+  xstyle?: StyleXStyles;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -347,6 +385,14 @@ function IconFromRegistry({
     return null;
   }
 
+  // The styling props (className, style, xstyle) are handled here so they
+  // COMPOSE with the internal astryx-icon + StyleX classes/styles instead of
+  // being shadowed by the later spread: xstyle folds into stylex.props, and
+  // className/style merge via mergeProps. Other span props keep their prior
+  // precedence (spread before the internal merge).
+  const restSpanProps =
+    (spanProps as React.HTMLAttributes<HTMLSpanElement>) ?? {};
+
   return (
     <span
       // Derived a11y — decorative (aria-hidden) by default, or a meaningful
@@ -354,10 +400,17 @@ function IconFromRegistry({
       // 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>)}
+      {...restSpanProps}
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.span, colorStyles[color], spanSizeStyles[size]),
+        stylex.props(
+          styles.span,
+          colorStyles[color],
+          spanSizeStyles[size],
+          xstyle,
+        ),
+        className ?? undefined,
+        style,
       )}>
       {resolvedIcon}
     </span>

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.test.tsx

@@ -31,18 +31,13 @@ describe('Item', () => {
   });
 
   it('renders marker', () => {
-    render(
-      <Item label="Item" marker={<span data-testid="marker">•</span>} />,
-    );
+    render(<Item label="Item" marker={<span data-testid="marker">•</span>} />);
     expect(screen.getByTestId('marker')).toBeInTheDocument();
   });
 
   it('renders startContent', () => {
     render(
-      <Item
-        label="Item"
-        startContent={<span data-testid="avatar">A</span>}
-      />,
+      <Item label="Item" startContent={<span data-testid="avatar">A</span>} />,
     );
     expect(screen.getByTestId('avatar')).toBeInTheDocument();
   });
@@ -255,12 +250,7 @@ describe('Item', () => {
   it('does not fire onClick when disabled item is clicked', async () => {
     const onClick = vi.fn();
     render(
-      <Item
-        label="Disabled"
-        onClick={onClick}
-        isDisabled
-        data-testid="item"
-      />,
+      <Item label="Disabled" onClick={onClick} isDisabled data-testid="item" />,
     );
     const item = screen.getByTestId('item');
     item.dispatchEvent(new MouseEvent('click', {bubbles: true}));
@@ -276,14 +266,46 @@ describe('Item', () => {
   // Selected state
   // ===========================================================================
 
-  it('applies aria-selected when isSelected', () => {
+  it('conveys selection via aria-current on the default div root', () => {
+    // aria-selected is invalid ARIA on a generic div (axe: aria-allowed-attr),
+    // so selection is exposed via aria-current, which is valid on any element.
     render(<Item label="Selected" isSelected data-testid="item" />);
-    expect(screen.getByTestId('item')).toHaveAttribute('aria-selected', 'true');
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).toHaveAttribute('aria-current', 'true');
   });
 
-  it('does not apply aria-selected when not selected', () => {
-    render(<Item label="Not Selected" data-testid="item" />);
-    expect(screen.getByTestId('item')).not.toHaveAttribute('aria-selected');
+  it('applies aria-selected (not aria-current) when the role permits it', () => {
+    render(
+      <Item label="Selected" isSelected role="option" data-testid="item" />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item).toHaveAttribute('aria-selected', 'true');
+    // A permitted role uses aria-selected; aria-current would be redundant.
+    expect(item).not.toHaveAttribute('aria-current');
+  });
+
+  it('falls back to aria-current when the role does not permit aria-selected', () => {
+    render(
+      <Item label="Selected" isSelected role="menuitem" data-testid="item" />,
+    );
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('applies neither aria-selected nor aria-current when not selected', () => {
+    render(<Item label="Not Selected" role="option" data-testid="item" />);
+    const item = screen.getByTestId('item');
+    expect(item).not.toHaveAttribute('aria-selected');
+    expect(item).not.toHaveAttribute('aria-current');
+  });
+
+  it('lets a consumer-provided aria-current win over the selection default', () => {
+    render(
+      <Item label="Step" isSelected aria-current="step" data-testid="item" />,
+    );
+    expect(screen.getByTestId('item')).toHaveAttribute('aria-current', 'step');
   });
 
   // ===========================================================================

package/src/Item/Item.tsx

@@ -131,7 +131,12 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   isHighlighted?: boolean;
 
   /**
-   * Selected state.
+   * Selected state. Always applies the selected visual styling. When `role`
+   * permits it (option, tab, row, gridcell, columnheader, rowheader, treeitem)
+   * the state is exposed as `aria-selected`; otherwise (e.g. a listitem or a
+   * bare div, where `aria-selected` is invalid ARIA) it falls back to
+   * `aria-current="true"` so assistive tech is still told which item is
+   * selected. A consumer-provided `aria-current` always wins.
    * @default false
    */
   isSelected?: boolean;
@@ -148,6 +153,24 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   'data-testid'?: string;
 }
 
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Roles on which WAI-ARIA permits the aria-selected attribute.
+ * https://www.w3.org/TR/wai-aria-1.2/#aria-selected
+ */
+const ARIA_SELECTED_ROLES = new Set([
+  'option',
+  'tab',
+  'row',
+  'gridcell',
+  'columnheader',
+  'rowheader',
+  'treeitem',
+]);
+
 // =============================================================================
 // Styles
 // =============================================================================
@@ -346,6 +369,11 @@ export function Item({
   // handles keyboard access. Skip the invisible button/anchor and put
   // onClick directly on the root element instead.
   const hasParentRole = role != null;
+  // aria-selected is only valid on selectable roles (option, tab, treeitem,
+  // grid cells). On the default div/li root the attribute is invalid ARIA
+  // (axe: aria-allowed-attr), so selection stays visual-only there — callers
+  // that need selection semantics pass a permitted role.
+  const allowsAriaSelected = role != null && ARIA_SELECTED_ROLES.has(role);
 
   const isStringLabel = typeof label === 'string';
   const isStringDescription = typeof description === 'string';
@@ -471,7 +499,15 @@ export function Item({
     <Component
       ref={ref as React.Ref<never>}
       {...restProps}
-      aria-selected={isSelected || undefined}
+      aria-selected={(allowsAriaSelected && isSelected) || undefined}
+      // aria-selected is invalid on roles that don't permit it (listitem, a
+      // bare div, etc.). For those, convey selection via aria-current — valid
+      // on any element — so the state still reaches AT. Written after
+      // {...restProps} so it must defer to a consumer-provided aria-current.
+      aria-current={
+        restProps['aria-current'] ??
+        (isSelected && !allowsAriaSelected ? true : undefined)
+      }
       aria-disabled={isDisabled || undefined}
       {...mergeProps(
         themeProps('item', {density, align}),