@fpkit/acss 6.3.0 → 6.4.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "6.3.0",
+  "version": "6.4.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"

package/src/components/alert/alert.scss

@@ -1,16 +1,3 @@
-/* Screen reader only utility class */
-.sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border-width: 0;
-}
-
 [role="alert"] {
   /* Success colors - WCAG AA compliant (mapped to semantic tokens) */
   --alert-success-bg: var(--color-success-bg);

package/src/components/buttons/icon-button.mdx

@@ -0,0 +1,204 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.React Components/Buttons/IconButton/Readme" />
+
+# IconButton
+
+## Summary
+
+`IconButton` is an accessible icon-button component that wraps the base `Button`
+with enforced accessible labelling and icon-specific defaults.
+
+It handles the two most common icon-button patterns:
+
+- **Icon-only** — a square tap target with a screen-reader label
+- **Icon + label** — icon with visible text that hides on narrow viewports
+
+`IconButton` extends all `Button` props (`size`, `variant`, `color`, `disabled`,
+etc.) and enforces one critical constraint at the TypeScript level: exactly one
+of `aria-label` or `aria-labelledby` must be present — passing both or neither
+is a compile-time error.
+
+---
+
+## Props
+
+| Prop              | Type                                                                 | Default    | Description                                                                                  |
+| ----------------- | -------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
+| `icon`            | `React.ReactNode`                                                    | —          | **Required.** The icon element rendered inside the button.                                   |
+| `aria-label`      | `string`                                                             | —          | Accessible name for icon-only buttons. XOR with `aria-labelledby`.                          |
+| `aria-labelledby` | `string`                                                             | —          | References an external element's `id` as the accessible name. XOR with `aria-label`.        |
+| `label`           | `string`                                                             | —          | Optional label text alongside the icon. Hidden below `48rem` (768px); always in the accessibility tree.|
+| `type`            | `'button' \| 'submit' \| 'reset'`                                    | `'button'` | Button type attribute. Required.                                                             |
+| `variant`         | `'icon' \| 'outline' \| 'text' \| 'pill'`                           | `'icon'`   | Style variant. Default `'icon'` gives a transparent, square, no-padding button.             |
+| `size`            | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                    | —          | Size token. Scales font size and height via `--btn-fs`.                                      |
+| `color`           | `'primary' \| 'secondary' \| 'danger' \| 'success' \| 'warning'`   | —          | Semantic color token. Sets `--btn-bg` and `--btn-color` via `data-color`.                   |
+| `disabled`        | `boolean`                                                            | `false`    | Disables the button using WCAG-compliant `aria-disabled` (stays keyboard-focusable).        |
+| `onClick`         | `(e: React.MouseEvent<HTMLButtonElement>) => void`                   | —          | Click handler.                                                                               |
+| `styles`          | `React.CSSProperties`                                                | —          | Inline styles — use to override CSS custom properties e.g. `--btn-color: red`.             |
+| `classes`         | `string`                                                             | —          | Additional CSS classes appended to the button element.                                       |
+
+---
+
+## Sizing — 3rem Fixed Tap Target
+
+The default `variant="icon"` applies a fixed `width: 3rem; height: 3rem` to
+every `IconButton` instance:
+
+```css
+button[data-icon-btn] {
+  width: 3rem;   /* 48px at default font size */
+  height: 3rem;  /* 48px at default font size */
+}
+```
+
+`3rem` equals **48px** at the browser's default 16px root font size, meeting
+the WCAG 2.5.5 (AAA) minimum target size recommendation of 44×44 CSS pixels.
+The fixed size ensures a consistent, touchable target regardless of icon size
+or parent context.
+
+When a `label` is present (the `has-label` variant), width becomes `max-content`
+and padding is restored to `0.75rem` inline, but the `3rem` height is preserved
+for a consistent touch target.
+
+---
+
+## Label Visibility
+
+When `label` is provided, the text is rendered in a `<span data-icon-label>`.
+Visibility is controlled entirely by CSS — no prop required:
+
+- **Below `48rem` (768px):** the span is visually hidden via the visually-hidden
+  technique applied by the `[data-icon-label]` media query in `icon-button.scss`.
+  The span remains in the DOM and the accessibility tree — screen readers
+  announce the label at every viewport size.
+- **At `48rem` and above:** the label is fully visible alongside the icon.
+
+The breakpoint is a SCSS variable (not a CSS custom property) because media
+query conditions are evaluated at parse time and cannot reference runtime values:
+
+```scss
+$icon-label-bp: 48rem !default; // Override before import to customise
+```
+
+---
+
+## Usage Examples
+
+### Icon-only button
+
+Requires `aria-label`. The label is only announced by screen readers — not
+visible on screen.
+
+```tsx
+import { IconButton } from "@fpkit/acss";
+
+<IconButton
+  type="button"
+  aria-label="Close menu"
+  icon={<CloseIcon />}
+/>
+```
+
+### Icon + visible label
+
+Use `variant="outline"` (or any non-`icon` variant) to restore padding alongside
+the label. The default `variant="icon"` sets `padding: 0`, which collapses the
+layout around a label. The label hides automatically on mobile (< 48rem) via CSS.
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Settings"
+  icon={<SettingsIcon />}
+  label="Settings"
+  variant="outline"
+/>
+```
+
+### Labelled by external element
+
+Use `aria-labelledby` to reference an existing label element in the DOM. Useful
+when the button sits next to a heading or description that already names the action.
+
+```tsx
+<span id="delete-label">Delete item</span>
+<IconButton
+  type="button"
+  aria-labelledby="delete-label"
+  icon={<TrashIcon />}
+/>
+```
+
+### Semantic color variants
+
+Color tokens apply to the icon via `currentColor` — the icon's `stroke` or
+`fill` inherits the button's `--btn-color`.
+
+```tsx
+<IconButton type="button" aria-label="Delete" icon={<TrashIcon />} color="danger" />
+<IconButton type="button" aria-label="Confirm" icon={<CheckIcon />} color="success" />
+<IconButton type="button" aria-label="Settings" icon={<GearIcon />} color="primary" variant="outline" />
+```
+
+### Disabled state
+
+Uses the WCAG-compliant `aria-disabled` pattern — the button remains focusable
+and visible in the tab order so keyboard users can discover it and read any
+associated tooltip or help text.
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Upload (unavailable)"
+  icon={<UploadIcon />}
+  disabled
+/>
+```
+
+### Custom color via CSS custom property
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Star"
+  icon={<StarIcon />}
+  styles={{ "--btn-color": "#f59e0b" }}
+/>
+```
+
+---
+
+## Accessibility Notes
+
+- **`aria-label` is required** for icon-only buttons. An icon with no label
+  gives screen reader users no indication of the button's purpose.
+- **XOR enforcement** — the TypeScript type allows exactly one of `aria-label`
+  or `aria-labelledby`. Passing both or neither is a compile-time error.
+- **`label` does not replace `aria-label`** — even when a visible `label` is
+  provided, you must still pass `aria-label` (or `aria-labelledby`). The `label`
+  prop controls visual presentation only; `aria-label` provides the computed
+  accessible name.
+- **`disabled` keeps focus** — `IconButton` uses `aria-disabled="true"` instead
+  of the native `disabled` attribute. The button stays in the tab order and can
+  receive focus, satisfying WCAG 2.1.1 (Keyboard) and 4.1.2 (Name, Role, Value).
+- **Icon `aria-hidden`** — always render icons with `aria-hidden="true"` so
+  screen readers do not double-announce both the SVG content and the button label.
+
+```tsx
+// Correct — icon is decorative, label carries the meaning
+<IconButton
+  type="button"
+  aria-label="Close"
+  icon={<svg aria-hidden="true">...</svg>}
+/>
+```
+
+---
+
+## Related
+
+- [Button README](./README.mdx) — base `Button` props and variants
+- [Button Styles](./STYLES.mdx) — full CSS custom property reference
+- [WCAG 2.5.5 Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)
+- [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks.html)

package/src/components/buttons/icon-button.scss

@@ -1,45 +1,83 @@
-// Breakpoint at which the label hides (icon-only on mobile).
+// Breakpoint at which the label becomes visible (mobile-first).
 // Override this variable in your own SCSS before importing to customise.
 // NOTE: CSS custom properties cannot be used in @media conditions — this must be a SCSS variable.
 $icon-label-bp: 48rem !default; // 768px
 
+// Global theming tokens for icon buttons.
+// Override in your theme stylesheet: :root { --icon-btn-size: 2.5rem; }
+// Minimum tap target recommended: 2.75rem (44px, WCAG 2.5.5).
+:root {
+  --icon-btn-size: 3rem;
+  --icon-btn-gap: 0.375rem;
+  --icon-btn-padding-inline: 0.75rem;
+}
+
+// Label is visually hidden by default (screen-reader accessible at all sizes).
+// Revealed at tablet+ via min-width media query below.
+[data-icon-btn] [data-icon-label],
+[data-icon-btn] .icon-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0); // fallback for older browsers
+  clip-path: inset(50%); // modern replacement (97%+ support)
+  white-space: nowrap;
+  border: 0;
+}
+
 // Color reset for all IconButton instances.
 // background stays transparent (set by button[data-style~="icon"]);
 // color defaults to currentColor so the icon inherits from context.
 // Override via styles={{ "--btn-color": "..." }} when a specific color is needed.
 button[data-icon-btn],
+button.icon-btn,
+[data-icon-btn],
 .icon-btn {
   --btn-color: currentColor;
-}
 
-// Layout when a visible label is present alongside the icon.
-// Higher specificity than button[data-style~="icon"] (which uses padding: unset)
-// so padding is restored without needing a consumer override.
-button[data-icon-btn~="has-label"],
-.icon-btn[data-icon-btn~="has-label"] {
-  gap: 0.375rem;
-  padding-inline: 0.75rem;
+  padding: 0;
+  width: var(--icon-btn-size);
+  height: var(--icon-btn-size);
+  display: inline-grid;
+  place-items: center;
 
-  [data-icon-label] {
-    font-size: var(--btn-fs, 0.875rem);
-    line-height: 1;
-    white-space: nowrap;
+  // Layout when a visible label is present alongside the icon.
+  // Higher specificity than button[data-style~="icon"] (which uses padding: unset)
+  // so padding is restored without needing a consumer override.
+  &[data-icon-btn~="has-label"] {
+    width: max-content;
+    min-width: var(--icon-btn-size);
+    gap: var(--icon-btn-gap);
+    padding-inline: var(--icon-btn-padding-inline);
+    grid-auto-flow: column; // keep icon + label side-by-side
+
+    [data-icon-label],
+    .icon-label {
+      font-size: var(--btn-fs, 0.875rem);
+      line-height: 1;
+      white-space: nowrap;
+    }
   }
 }
 
-// Hide label text visually on mobile — icon only.
-// Uses visually-hidden technique so the span stays in the accessibility tree;
-// screen readers always read it (display:none would remove it from the a11y tree).
-@media (max-width: #{$icon-label-bp}) {
-  [data-icon-label] {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    padding: 0;
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
+// Reveal label text at tablet+ — icon + label visible together.
+// Uses min-width (mobile-first): hidden by default, shown at 48rem+.
+// BREAKING CHANGE: Previously max-width (desktop-first).
+@media (min-width: #{$icon-label-bp}) {
+  [data-icon-btn] [data-icon-label],
+  [data-icon-btn] .icon-label {
+    position: static;
+    width: auto;
+    height: auto;
+    padding: unset;
+    margin: unset;
+    overflow: visible;
+    clip: unset;
+    clip-path: unset;
     white-space: nowrap;
-    border: 0;
+    border: unset;
   }
 }

package/src/components/buttons/icon-button.tsx

@@ -15,11 +15,13 @@ export type IconButtonProps = Omit<ButtonProps, "children"> &
     icon: React.ReactNode;
     /**
      * Optional text shown alongside the icon at desktop widths.
-     * Hidden visually below the `$icon-label-bp` SCSS breakpoint (default 48rem / 768px),
-     * but remains in the accessibility tree — screen readers always announce it.
+     * Visually hidden below the `$icon-label-bp` SCSS breakpoint (default 48rem / 768px)
+     * via a media query on `[data-icon-label]`, but always present in the accessibility
+     * tree — screen readers announce it at every viewport size.
      *
-     * NOTE: When `label` is used, the default `variant="icon"` removes padding.
-     * Override with a different variant (e.g. `variant="outline"`) for a padded layout.
+     * NOTE: When `label` is provided, the default `variant="icon"` removes padding.
+     * Use `variant="outline"` (or another padded variant) to restore layout padding
+     * alongside the label.
      */
     label?: string;
     /** Button type: button, submit, or reset. Required. */
@@ -29,15 +31,16 @@ export type IconButtonProps = Omit<ButtonProps, "children"> &
 /**
  * Accessible icon button component. Wraps `Button` with:
  * - Required accessible label via `aria-label` or `aria-labelledby` (XOR enforced)
- * - Optional visible `label` text that hides on mobile (visual only — always in a11y tree)
+ * - Optional `label` text hidden on mobile (< 48rem), visible on desktop — always in a11y tree
  * - `variant="icon"` default (square, no padding)
+ * - Fixed `3rem × 3rem` tap target (48px at default root font size — WCAG 2.5.5 AAA)
  *
  * @example
  * // Icon only
  * <IconButton type="button" aria-label="Close menu" icon={<CloseIcon />} />
  *
  * @example
- * // Icon + label (label hides on mobile)
+ * // Icon + label (label hides on mobile, visible at >= 48rem / 768px)
  * <IconButton
  *   type="button"
  *   aria-label="Settings"

package/src/components/dialog/dialog-modal.stories.tsx

@@ -3,6 +3,23 @@ import { within, expect, userEvent, waitFor } from "storybook/test";
 
 import DialogModal from "./dialog-modal";
 import WithInstructions from "#/decorators/instructions";
+
+// Inline SVG icons for stories — no external icon dependency required
+const SettingsIcon = () => (
+  <svg width="1em" height="1em" viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" strokeWidth={2}>
+    <circle cx="12" cy="12" r="3" />
+    <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+  </svg>
+);
+
+const TrashIcon = () => (
+  <svg width="1em" height="1em" viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" strokeWidth={2}>
+    <polyline points="3 6 5 6 21 6" />
+    <path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6" />
+    <path d="M10 11v6M14 11v6" />
+    <path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2" />
+  </svg>
+);
 const meta: Meta<typeof DialogModal> = {
   title: "FP.React Components/Dialog/DialogModal",
   component: DialogModal,
@@ -110,3 +127,57 @@ export const ModalInteractions: Story = {
     });
   },
 } as Story;
+
+export const IconTrigger: Story = {
+  args: {
+    children: "This dialog was opened from an icon button trigger.",
+    dialogTitle: "Settings",
+    btnLabel: "Settings",
+    icon: <SettingsIcon />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Icon button opens dialog", async () => {
+      const iconButton = canvas.getByRole("button", { name: /settings/i });
+      expect(iconButton).toHaveAttribute("aria-haspopup", "dialog");
+      await userEvent.click(iconButton, { delay: 500 });
+      const dialog = canvas.getByRole("dialog");
+      expect(dialog).toBeVisible();
+    });
+
+    await step("Close dialog", async () => {
+      const closeButton = canvas.getByRole("button", { name: /close dialog/i });
+      await userEvent.click(closeButton, { delay: 500 });
+    });
+  },
+} as Story;
+
+export const IconTriggerWithOutlineVariant: Story = {
+  args: {
+    children: "This dialog uses an icon button with outline variant and visible label.",
+    dialogTitle: "Delete Item",
+    btnLabel: "Delete",
+    icon: <TrashIcon />,
+    btnProps: { variant: "outline", color: "danger" },
+    onConfirm: () => {},
+    confirmLabel: "Delete",
+    cancelLabel: "Cancel",
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Icon button with label opens dialog", async () => {
+      const iconButton = canvas.getByRole("button", { name: /delete/i });
+      expect(iconButton).toHaveAttribute("aria-haspopup", "dialog");
+      await userEvent.click(iconButton, { delay: 500 });
+      const dialog = canvas.getByRole("dialog");
+      expect(dialog).toBeVisible();
+    });
+
+    await step("Close with cancel", async () => {
+      const cancelButton = canvas.getByRole("button", { name: /cancel/i });
+      await userEvent.click(cancelButton, { delay: 500 });
+    });
+  },
+} as Story;

package/src/components/dialog/dialog-modal.tsx

@@ -1,6 +1,7 @@
 import React, { useState, useRef, useCallback, useEffect } from "react";
 import Dialog from "./dialog";
 import Button from "#components/buttons/button.jsx";
+import { IconButton } from "#components/buttons/icon-button.jsx";
 import type { DialogModalProps } from "./dialog.types";
 
 /**
@@ -34,6 +35,7 @@ import type { DialogModalProps } from "./dialog.types";
  * @param {boolean} [props.hideFooter=false] - If true, hides the footer with action buttons
  * @param {string} [props.className] - Additional CSS classes for the dialog
  * @param {string} [props.dialogLabel] - Optional aria-label for the dialog
+ * @param {ReactElement} [props.icon] - Optional icon element. When provided, renders IconButton as trigger.
  * @returns {JSX.Element} A dialog with trigger button and automatic state management
  *
  * @example
@@ -49,6 +51,19 @@ import type { DialogModalProps } from "./dialog.types";
  *   Are you sure you want to delete this item? This action cannot be undone.
  * </DialogModal>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon trigger — renders IconButton with visible label at desktop widths
+ * <DialogModal
+ *   dialogTitle="Settings"
+ *   btnLabel="Settings"
+ *   icon={<SettingsIcon />}
+ *   btnProps={{ variant: "outline" }}
+ * >
+ *   Settings content here.
+ * </DialogModal>
+ * ```
  */
 export const DialogModal: React.FC<DialogModalProps> = ({
   isAlertDialog = false,
@@ -65,6 +80,7 @@ export const DialogModal: React.FC<DialogModalProps> = ({
   className,
   hideFooter = false,
   btnProps,
+  icon,
 }) => {
   const [isOpen, setIsOpen] = useState(false);
   const lastFocusedElement = useRef<HTMLElement | null>(null);
@@ -103,16 +119,26 @@ export const DialogModal: React.FC<DialogModalProps> = ({
     }
   }, [isOpen]);
 
-  const triggerButtonProps = {
+  const sharedTriggerProps = {
     type: "button" as const,
     onClick: handleButtonClick,
-    "data-btn": btnSize,
+    "aria-haspopup": "dialog" as const,
     ...btnProps,
   };
 
   return (
     <>
-      <Button {...triggerButtonProps}>{btnLabel}</Button>
+      {icon ? (
+        <IconButton
+          icon={icon}
+          aria-label={btnLabel}
+          label={btnLabel}
+          size={btnSize}
+          {...sharedTriggerProps}
+        />
+      ) : (
+        <Button data-btn={btnSize} {...sharedTriggerProps}>{btnLabel}</Button>
+      )}
       <Dialog
         isOpen={isOpen}
         onOpenChange={handleOpenChange}

package/src/components/dialog/dialog.scss

@@ -83,6 +83,7 @@ dialog {
   button[type="button"] {
     background-color: var(--dialog-button-bg);
     border: var(--dialog-button-border);
+    color: var(--dialog-close-color);
     cursor: pointer;
 
     &:hover {

package/src/components/dialog/dialog.test.tsx

@@ -446,5 +446,124 @@ describe("DialogModal", () => {
       expect(triggerButton).toBeInTheDocument();
       expect(triggerButton).not.toBeDisabled();
     });
+
+    it("adds aria-haspopup='dialog' to the regular button trigger", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open">
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      expect(triggerButton).toHaveAttribute("aria-haspopup", "dialog");
+    });
+  });
+
+  describe("Icon Button Trigger", () => {
+    const TestIcon = () => (
+      <svg data-testid="test-icon" aria-hidden="true">
+        <circle cx="12" cy="12" r="10" />
+      </svg>
+    );
+
+    it("renders IconButton when icon prop is provided", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Settings" icon={<TestIcon />}>
+          Content
+        </DialogModal>
+      );
+
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      expect(iconButton).toHaveAttribute("data-icon-btn");
+    });
+
+    it("renders regular Button when icon prop is not provided", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open">
+          Content
+        </DialogModal>
+      );
+
+      const button = screen.getByRole("button", { name: /open/i });
+      expect(button).not.toHaveAttribute("data-icon-btn");
+    });
+
+    it("uses btnLabel as aria-label on the icon button", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Settings" icon={<TestIcon />}>
+          Content
+        </DialogModal>
+      );
+
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      expect(iconButton).toHaveAttribute("aria-label", "Settings");
+    });
+
+    it("passes btnLabel as visible label on the icon button", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Settings" icon={<TestIcon />}>
+          Content
+        </DialogModal>
+      );
+
+      // IconButton renders the label in a span with data-icon-label
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      expect(iconButton.querySelector("[data-icon-label]")).toHaveTextContent("Settings");
+    });
+
+    it("adds aria-haspopup='dialog' to the icon button trigger", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Settings" icon={<TestIcon />}>
+          Content
+        </DialogModal>
+      );
+
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      expect(iconButton).toHaveAttribute("aria-haspopup", "dialog");
+    });
+
+    it("opens dialog when icon button is clicked", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <DialogModal dialogTitle="Test Dialog" btnLabel="Settings" icon={<TestIcon />}>
+          Dialog content
+        </DialogModal>
+      );
+
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      await user.click(iconButton);
+
+      await waitFor(() => {
+        expect(screen.getByRole("dialog")).toBeInTheDocument();
+        expect(screen.getByText("Dialog content")).toBeInTheDocument();
+      });
+    });
+
+    it("applies btnSize to the icon button", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Settings" icon={<TestIcon />} btnSize="lg">
+          Content
+        </DialogModal>
+      );
+
+      const iconButton = screen.getByRole("button", { name: /settings/i });
+      expect(iconButton).toHaveAttribute("data-btn", "lg");
+    });
+
+    it("forwards btnProps to the icon button", () => {
+      render(
+        <DialogModal
+          dialogTitle="Test"
+          btnLabel="Settings"
+          icon={<TestIcon />}
+          btnProps={{ "data-testid": "icon-trigger" }}
+        >
+          Content
+        </DialogModal>
+      );
+
+      expect(screen.getByTestId("icon-trigger")).toBeInTheDocument();
+    });
   });
 });