@fpkit/acss 6.2.0 → 6.4.0

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

@@ -0,0 +1,83 @@
+// 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;
+
+  padding: 0;
+  width: var(--icon-btn-size);
+  height: var(--icon-btn-size);
+  display: inline-grid;
+  place-items: center;
+
+  // 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;
+    }
+  }
+}
+
+// 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: unset;
+  }
+}

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

@@ -0,0 +1,200 @@
+import type { StoryObj, Meta } from "@storybook/react-vite";
+import { within, userEvent, expect, fn } from "storybook/test";
+
+import { IconButton } from "./icon-button";
+import "./button.scss";
+import "./icon-button.scss";
+
+// Minimal inline SVG icons for stories — no external icon dependency required
+const CloseIcon = () => (
+  <svg width="1em" height="1em" viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" strokeWidth={2}>
+    <line x1="18" y1="6" x2="6" y2="18" />
+    <line x1="6" y1="6" x2="18" y2="18" />
+  </svg>
+);
+
+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 iconClicked = fn();
+
+const meta = {
+  title: "FP.React Components/Buttons/IconButton",
+  component: IconButton,
+  tags: ["beta"],
+  args: {
+    type: "button",
+    icon: <CloseIcon />,
+    "aria-label": "Close",
+    onClick: iconClicked,
+  },
+} as Meta;
+
+export default meta;
+type Story = StoryObj<typeof IconButton>;
+
+/**
+ * Default icon-only button. Requires `aria-label` for screen reader accessibility.
+ */
+export const IconButtonDefault: Story = {
+  args: {
+    "aria-label": "Close",
+    icon: <CloseIcon />,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button", { name: "Close" });
+
+    await step("IconButton is rendered with aria-label", async () => {
+      expect(button).toBeInTheDocument();
+      expect(button).toHaveAttribute("aria-label", "Close");
+    });
+
+    await step("IconButton receives focus on tab", async () => {
+      await userEvent.tab();
+      expect(button).toHaveFocus();
+    });
+
+    await step("IconButton click handler fires", async () => {
+      await userEvent.click(button);
+      expect(iconClicked).toHaveBeenCalled();
+    });
+  },
+};
+
+/**
+ * Uses `aria-labelledby` instead of `aria-label` — references an existing element in the DOM.
+ * The XOR type means passing both `aria-label` and `aria-labelledby` is a TypeScript error.
+ */
+export const IconButtonLabelledBy: Story = {
+  render: () => (
+    <div>
+      <span id="icon-btn-label" style={{ marginInlineEnd: "0.5rem" }}>
+        Delete item
+      </span>
+      <IconButton
+        type="button"
+        aria-labelledby="icon-btn-label"
+        icon={<TrashIcon />}
+      />
+    </div>
+  ),
+};
+
+/**
+ * Icon + visible label. Label hides below 768px (overridable via `$icon-label-bp` SCSS variable).
+ * Resize the viewport to see the responsive behavior.
+ * NOTE: `variant="outline"` overrides the default `variant="icon"` to restore padding.
+ */
+export const IconButtonWithLabel: Story = {
+  args: {
+    "aria-label": "Settings",
+    icon: <SettingsIcon />,
+    label: "Settings",
+    variant: "outline",
+  },
+};
+
+/**
+ * All style variants — icon (default), outline, text, and pill.
+ * `icon` is the default: transparent background, currentColor icon, square touch target.
+ * Switch `variant` to restore background or border as needed.
+ */
+export const IconButtonVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center", flexWrap: "wrap" }}>
+      <IconButton type="button" aria-label="Icon variant (default)" icon={<SettingsIcon />} />
+      <IconButton type="button" aria-label="Outline variant" icon={<SettingsIcon />} variant="outline" />
+      <IconButton type="button" aria-label="Text variant" icon={<SettingsIcon />} variant="text" />
+      <IconButton type="button" aria-label="Pill variant" icon={<SettingsIcon />} variant="pill" />
+    </div>
+  ),
+};
+
+/**
+ * Size variants — xs through 2xl. Height and touch target scale with font size
+ * via the `--btn-height: calc(var(--btn-fs) * 2.75)` formula.
+ */
+export const IconButtonSizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center", flexWrap: "wrap" }}>
+      <IconButton type="button" aria-label="Close (xs)" icon={<CloseIcon />} size="xs" />
+      <IconButton type="button" aria-label="Close (sm)" icon={<CloseIcon />} size="sm" />
+      <IconButton type="button" aria-label="Close (md)" icon={<CloseIcon />} size="md" />
+      <IconButton type="button" aria-label="Close (lg)" icon={<CloseIcon />} size="lg" />
+      <IconButton type="button" aria-label="Close (xl)" icon={<CloseIcon />} size="xl" />
+      <IconButton type="button" aria-label="Close (2xl)" icon={<CloseIcon />} size="2xl" />
+    </div>
+  ),
+};
+
+/**
+ * All semantic color variants. Color sets `--btn-bg` and `--btn-color` via
+ * `data-color` — icon buttons keep a transparent background by default so the
+ * icon itself inherits the color token via `currentColor`.
+ */
+export const IconButtonColors: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center", flexWrap: "wrap" }}>
+      <IconButton type="button" aria-label="Primary" icon={<SettingsIcon />} color="primary" />
+      <IconButton type="button" aria-label="Secondary" icon={<SettingsIcon />} color="secondary" />
+      <IconButton type="button" aria-label="Danger" icon={<TrashIcon />} color="danger" />
+      <IconButton type="button" aria-label="Success" icon={<CloseIcon />} color="success" />
+      <IconButton type="button" aria-label="Warning" icon={<CloseIcon />} color="warning" />
+    </div>
+  ),
+};
+
+/**
+ * Outline variant across all color tokens. The `outline` variant restores a border
+ * and uses `currentColor` for both border and icon — color sets the inherited value.
+ */
+export const IconButtonOutlineColors: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center", flexWrap: "wrap" }}>
+      <IconButton type="button" aria-label="Primary outline" icon={<SettingsIcon />} variant="outline" color="primary" />
+      <IconButton type="button" aria-label="Secondary outline" icon={<SettingsIcon />} variant="outline" color="secondary" />
+      <IconButton type="button" aria-label="Danger outline" icon={<TrashIcon />} variant="outline" color="danger" />
+      <IconButton type="button" aria-label="Success outline" icon={<CloseIcon />} variant="outline" color="success" />
+      <IconButton type="button" aria-label="Warning outline" icon={<CloseIcon />} variant="outline" color="warning" />
+    </div>
+  ),
+};
+
+/**
+ * Disabled state — uses the WCAG-compliant `aria-disabled` pattern.
+ * The button remains focusable but all interactions are blocked.
+ */
+export const IconButtonDisabled: Story = {
+  args: {
+    "aria-label": "Close (disabled)",
+    icon: <CloseIcon />,
+    disabled: true,
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button", { name: "Close (disabled)" });
+
+    await step("Disabled button has aria-disabled attribute", async () => {
+      expect(button).toHaveAttribute("aria-disabled", "true");
+    });
+
+    await step("Disabled button remains focusable", async () => {
+      await userEvent.tab();
+      expect(button).toHaveFocus();
+    });
+  },
+};

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

@@ -0,0 +1,132 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi } from "vitest";
+import { IconButton } from "./icon-button";
+
+const TestIcon = () => <svg data-testid="test-icon" aria-hidden="true" />;
+
+describe("IconButton", () => {
+  it("renders a button element with aria-label", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute("aria-label", "Close");
+  });
+
+  it("renders a button element with aria-labelledby", () => {
+    render(
+      <>
+        <span id="lbl">Delete item</span>
+        <IconButton type="button" aria-labelledby="lbl" icon={<TestIcon />} />
+      </>
+    );
+    const button = screen.getByRole("button", { name: "Delete item" });
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute("aria-labelledby", "lbl");
+  });
+
+  it("renders the icon as a child of the button", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    expect(screen.getByTestId("test-icon")).toBeInTheDocument();
+  });
+
+  it("renders label text when label prop is provided", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    expect(screen.getByText("Settings")).toBeInTheDocument();
+  });
+
+  it("applies data-icon-label attribute to the label span", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    const labelSpan = screen.getByText("Settings");
+    expect(labelSpan).toHaveAttribute("data-icon-label");
+  });
+
+  it("applies data-icon-btn='has-label' to the button when label is provided", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    const button = screen.getByRole("button", { name: "Settings" });
+    expect(button).toHaveAttribute("data-icon-btn", "has-label");
+  });
+
+  it("does not render a label span when label prop is omitted", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    expect(document.querySelector("[data-icon-label]")).toBeNull();
+  });
+
+  it("sets data-icon-btn to 'icon' when label is omitted", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("data-icon-btn", "icon");
+  });
+
+  it("fires the click handler when clicked", async () => {
+    const handleClick = vi.fn();
+    render(
+      <IconButton
+        type="button"
+        aria-label="Close"
+        icon={<TestIcon />}
+        onClick={handleClick}
+      />
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire click handler when disabled", async () => {
+    const handleClick = vi.fn();
+    render(
+      <IconButton
+        type="button"
+        aria-label="Close"
+        icon={<TestIcon />}
+        disabled
+        onClick={handleClick}
+      />
+    );
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("aria-disabled", "true");
+    await userEvent.click(button);
+    expect(handleClick).toHaveBeenCalledTimes(0);
+  });
+
+  it("defaults variant to 'icon'", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("data-style", "icon");
+  });
+
+  it("accepts a variant override", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        variant="outline"
+      />
+    );
+    const button = screen.getByRole("button", { name: "Settings" });
+    expect(button).toHaveAttribute("data-style", "outline");
+  });
+});

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

@@ -0,0 +1,75 @@
+import React from "react";
+import { Button, type ButtonProps } from "./button";
+
+/**
+ * XOR constraint: exactly one of aria-label or aria-labelledby is required.
+ * Passing both or neither is a TypeScript compile-time error.
+ * Satisfies WCAG 2.1 SC 1.1.1 (Non-text Content).
+ */
+type WithAriaLabel = { "aria-label": string; "aria-labelledby"?: never };
+type WithAriaLabelledBy = { "aria-labelledby": string; "aria-label"?: never };
+
+export type IconButtonProps = Omit<ButtonProps, "children"> &
+  (WithAriaLabel | WithAriaLabelledBy) & {
+    /** The icon element rendered inside the button. */
+    icon: React.ReactNode;
+    /**
+     * Optional text shown alongside the icon at desktop widths.
+     * 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 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. */
+    type: "button" | "submit" | "reset";
+  };
+
+/**
+ * Accessible icon button component. Wraps `Button` with:
+ * - Required accessible label via `aria-label` or `aria-labelledby` (XOR enforced)
+ * - 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, visible at >= 48rem / 768px)
+ * <IconButton
+ *   type="button"
+ *   aria-label="Settings"
+ *   icon={<SettingsIcon />}
+ *   label="Settings"
+ *   variant="outline"
+ * />
+ *
+ * @example
+ * // Labelled by external element
+ * <span id="btn-label">Delete item</span>
+ * <IconButton type="button" aria-labelledby="btn-label" icon={<TrashIcon />} />
+ */
+export const IconButton = ({
+  icon,
+  label,
+  variant = "icon",
+  type = "button",
+  ...props
+}: IconButtonProps) => (
+  <Button
+    variant={variant}
+    data-icon-btn={label ? "has-label" : "icon"}
+    {...props}
+    type={type}
+  >
+    {icon}
+    {label && <span data-icon-label>{label}</span>}
+  </Button>
+);
+
+IconButton.displayName = "IconButton";

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 {