@astryxdesign/core 0.1.8 → 0.1.9-canary.1887ee2

package/src/FileInput/FileInput.test.tsx

@@ -147,16 +147,33 @@ describe('FileInput', () => {
     expect(screen.getByText('Upload')).toBeInTheDocument();
   });
 
-  it('sets aria-required when isRequired is true', () => {
+  it('conveys required state through the accessible description', () => {
     render(
       <FileInput label="Resume" isRequired value={null} onChange={() => {}} />,
     );
-    // aria-required lives on the focusable role="button" wrapper, not the
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    // Required is conveyed via a visually hidden "Required" node referenced
+    // from aria-describedby on the focusable role="button" trigger — not the
     // hidden file input (forms-6).
-    expect(screen.getByRole('button', {name: 'Resume'})).toHaveAttribute(
-      'aria-required',
-      'true',
+    expect(trigger).toHaveAccessibleDescription(/Required/);
+    // aria-required is not a supported property of role="button" in
+    // WAI-ARIA 1.2 (AT does not announce it), so it must never appear.
+    expect(trigger).not.toHaveAttribute('aria-required');
+  });
+
+  it('combines required with the description in the accessible description', () => {
+    render(
+      <FileInput
+        label="Resume"
+        description="PDF only"
+        isRequired
+        value={null}
+        onChange={() => {}}
+      />,
     );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).toHaveAccessibleDescription(/PDF only/);
+    expect(trigger).toHaveAccessibleDescription(/Required/);
   });
 
   it('places aria-describedby on the focusable button, not the hidden input (forms-6)', () => {
@@ -176,11 +193,11 @@ describe('FileInput', () => {
     expect(input).toHaveAttribute('aria-hidden', 'true');
   });
 
-  it('does not set aria-required by default', () => {
+  it('does not mention required without isRequired', () => {
     render(<FileInput label="Resume" value={null} onChange={() => {}} />);
-    expect(screen.getByRole('button', {name: 'Resume'})).not.toHaveAttribute(
-      'aria-required',
-    );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).not.toHaveAccessibleDescription(/Required/);
+    expect(trigger).not.toHaveAttribute('aria-required');
   });
 
   it('sets disabled attribute when isDisabled is true', () => {
@@ -348,9 +365,44 @@ describe('FileInput', () => {
       fireEvent.change(fileInputEl(), {
         target: {files: [createFile('note.txt', 100)]},
       });
-      // A rejected selection creates no polite region (only the error goes to
-      // the existing role="status" region).
-      expect(politeRegion()).toBeNull();
+      // A rejected selection announces nothing politely. (The region pair may
+      // exist because the validation error itself is announced assertively via
+      // FieldStatus, but the polite channel must stay empty.)
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
+
+    it('announces a validation error exactly once across live regions', async () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          accept=".pdf"
+        />,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('note.txt', 100)]},
+      });
+      const errorText = '"note.txt" is not an accepted file type';
+      // The error lands in the assertive announce region (via the FieldStatus
+      // the derived error status mounts)…
+      await waitFor(() => {
+        expect(
+          document.querySelector('[data-astryx-live-region="assertive"]'),
+        ).toHaveTextContent(errorText);
+      });
+      // …and in exactly one live region overall. FileInput's own role="status"
+      // region used to duplicate the FieldStatus announcement, so the same
+      // error was read twice (assertively, then politely).
+      const liveRegions = Array.from(
+        document.querySelectorAll(
+          '[role="status"], [role="alert"], [aria-live]',
+        ),
+      );
+      const regionsWithError = liveRegions.filter(el =>
+        (el.textContent ?? '').includes(errorText),
+      );
+      expect(regionsWithError).toHaveLength(1);
     });
   });
 
@@ -641,6 +693,54 @@ describe('FileInput', () => {
     });
   });
 
+  describe('trigger accessible name', () => {
+    it('includes the selected file name in the trigger name', () => {
+      const file = createFile('report.pdf', 1024, 'application/pdf');
+      render(<FileInput label="Document" value={file} onChange={() => {}} />);
+      expect(
+        screen.getByRole('button', {name: 'Document, report.pdf'}),
+      ).toBeInTheDocument();
+    });
+
+    it('includes all selected file names when multiple files are selected', () => {
+      const files = [createFile('a.txt', 100), createFile('b.txt', 200)];
+      render(
+        <FileInput
+          label="Files"
+          value={files}
+          onChange={() => {}}
+          isMultiple
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Files, a.txt, b.txt'}),
+      ).toBeInTheDocument();
+    });
+
+    it('uses exactly the label when no files are selected', () => {
+      render(<FileInput label="Document" value={null} onChange={() => {}} />);
+      expect(screen.getByRole('button', {name: 'Document'})).toHaveAttribute(
+        'aria-label',
+        'Document',
+      );
+    });
+
+    it('includes the selected file name in dropzone mode', () => {
+      const file = createFile('doc.pdf', 100, 'application/pdf');
+      render(
+        <FileInput
+          label="Upload"
+          value={file}
+          onChange={() => {}}
+          mode="dropzone"
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Upload, doc.pdf'}),
+      ).toBeInTheDocument();
+    });
+  });
+
   describe('data-testid', () => {
     it('passes data-testid to native input', () => {
       render(
@@ -800,3 +900,26 @@ describe('FileInput', () => {
     });
   });
 });
+
+
+describe('FileInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <FileInput label="Upload" value={null} onChange={() => {}} status={{type: 'error', message: 'Something went wrong'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/FileInput/FileInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
  * @output Exports FileInput component, FileInputProps, FileInputStatus
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -41,9 +41,11 @@ import {
   InputClearButton,
   type InputStatus,
   type InputStatusType,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useTooltip} from '../Tooltip';
 
@@ -246,17 +248,6 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
-  liveRegion: {
-    position: 'absolute',
-    width: 1,
-    height: 1,
-    padding: 0,
-    margin: -1,
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
 });
 
 const statusBorderStyles = stylex.create({
@@ -358,6 +349,13 @@ export interface FileInputProps extends Omit<
    * Validation status for the input.
    */
   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;
   /**
    * Description text displayed below the label.
    */
@@ -414,6 +412,7 @@ export function FileInput({
   isRequired = false,
   isLoading = false,
   status: statusProp,
+  statusVariant = 'attached',
   description,
   placeholder,
   mode = 'input',
@@ -430,15 +429,16 @@ export function FileInput({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
-  const liveRegionID = useId();
+  const requiredID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | null>(null);
   const [, startTransition] = useTransition();
 
   // Announce successful file selection to screen readers via a persistent
-  // live region (forms-17). The component's own role="status" region only
-  // carries validation errors, so a successful attach was previously silent.
+  // live region (forms-17). Validation errors are announced (assertively) by
+  // the FieldStatus that the derived error status mounts, so only the
+  // successful attach needs an explicit announcement here.
   const announce = useAnnounce();
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
@@ -474,10 +474,18 @@ export function FileInput({
     success: 'success',
   };
 
+  // Required state. `aria-required` is not a supported property of
+  // role="button" in WAI-ARIA 1.2 (AT does not announce it there), so the
+  // trigger instead points its aria-describedby at a visually hidden
+  // "Required" span — mirroring the Field label's visible indicator (where
+  // isOptional takes precedence) and the pattern Slider uses for its thumbs.
+  const conveysRequired = isRequired && !isOptional;
+
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      conveysRequired ? requiredID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -515,8 +523,9 @@ export function FileInput({
       onChange(result);
 
       // Announce the successful selection politely. Validation errors are
-      // handled by the role="status" region below, so only announce the
-      // attach here (do not double-announce errors).
+      // announced assertively by the FieldStatus that the derived error
+      // status mounts, so only announce the attach here (do not
+      // double-announce errors).
       if (errors.length === 0) {
         announce(
           valid.length === 1
@@ -728,6 +737,7 @@ export function FileInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
@@ -745,13 +755,27 @@ export function FileInput({
         aria-disabled={showsDisabledMessage ? 'true' : undefined}
         onClick={handleClick}
         onKeyDown={handleKeyDown}
-        aria-label={label}
+        // aria-label suppresses child content from the accessible name, so
+        // compose the selected filenames into it — otherwise a screen-reader
+        // user refocusing the control hears only the field label and cannot
+        // tell what (if anything) is attached.
+        aria-label={
+          hasFiles && fileNames
+            ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
+            : label
+        }
         aria-busy={isLoading || undefined}
         // These describe the operable control, so they belong on the focusable
         // role="button" wrapper — not the hidden tabIndex={-1} file input the
-        // user never focuses (forms-6).
+        // user never focuses (forms-6). Required state is conveyed through
+        // the visually hidden "Required" node in aria-describedby, not
+        // aria-required, which role="button" does not support in ARIA 1.2.
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired ? 'true' : undefined}
+        // aria-invalid is likewise unsupported on role="button", but it stays:
+        // a message-less error status (`status={{type: 'error'}}`) has no
+        // described-by replacement, and some AT still honor the attribute, so
+        // removing it would not be strictly better. Errors *with* a message
+        // are described via statusMessageID above.
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         {...dragDropProps}
         {...mergeProps(
@@ -785,16 +809,17 @@ export function FileInput({
         />
         {isDropzone ? renderDropzoneContent() : renderCompactContent()}
         {hasFiles && !isDisabled && !isLoading && (
-          <InputClearButton label={t('@astryx.fileInput.clearLabel', {label})} onClick={handleClear} />
+          <InputClearButton
+            label={t('@astryx.fileInput.clearLabel', {label})}
+            onClick={handleClear}
+          />
         )}
       </div>
-      <div
-        id={liveRegionID}
-        role="status"
-        aria-live="polite"
-        {...stylex.props(styles.liveRegion)}>
-        {validationError}
-      </div>
+      {conveysRequired && (
+        <VisuallyHidden id={requiredID}>
+          {t('@astryx.fileInput.required')}
+        </VisuallyHidden>
+      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/HoverCard/HoverCard.doc.mjs

@@ -79,6 +79,12 @@ export const docs = {
           description: 'Enables or disables the hover and focus triggers.',
           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: 'onOpenChange',
           type: '(isOpen: boolean) => void',
@@ -188,6 +194,12 @@ export const docsZh = {
           description: '启用或禁用悬停和聚焦触发器。',
           default: 'true',
         },
+        {
+          name: 'label',
+          type: 'string',
+          description:
+            '悬浮卡片弹出层的无障碍名称。提供时，弹出层以具名的 role="dialog" 暴露；省略时，回退为 role="group"（group 可以合法地没有名称）。',
+        },
         {
           name: 'onOpenChange',
           type: '(isOpen: boolean) => void',
@@ -252,6 +264,7 @@ export const docsDense = {
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger hover card.',
         isEnabled: 'Enable/disable hover + focus triggers.',
+        label: 'Accessible name for the popup. With label: named role="dialog"; without: role="group".',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',
         isDefaultOpen: 'Show hover card on mount. Still dismissible.',

package/src/HoverCard/HoverCard.test.tsx

@@ -58,15 +58,34 @@ describe('HoverCard', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
-  it('gives the floating layer role="dialog"', () => {
+  it('exposes the floating layer as role="group" when no label is provided', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
       </HoverCard>,
     );
-    expect(screen.getByRole('dialog', {hidden: true})).toHaveTextContent(
+    // A group may validly be unnamed; an unnamed dialog may not. Without a
+    // label the layer must not claim the dialog role.
+    expect(screen.getByRole('group', {hidden: true})).toHaveTextContent(
       'Card content',
     );
+    expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+  });
+
+  it('exposes the floating layer as a named dialog when label is provided', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile preview">
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    // The layer is hidden while closed, so assert the accessible name via the
+    // aria-label attribute on the role-carrying element (same pattern as the
+    // Popover dialogLabel test) — accname computation returns '' for hidden
+    // elements.
+    const dialog = screen.getByRole('dialog', {hidden: true});
+    expect(dialog).toHaveAttribute('aria-label', 'Profile preview');
+    expect(dialog).toHaveTextContent('Card content');
+    expect(screen.queryByRole('group', {hidden: true})).toBeNull();
   });
 
   it('wraps element children in an inline-safe span', () => {

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

@@ -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

@@ -37,7 +37,7 @@ 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.',
     },
   ],
   theming: {
@@ -50,7 +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: '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.' },
@@ -121,6 +121,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.' },

package/src/Icon/Icon.tsx

@@ -229,12 +229,17 @@ 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" />
    * ```
    */

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'));
+  });
 });