@edux-design/modals 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @edux-design/modals
+
+## 0.1.1
+
+### Patch Changes
+
+- Minor changes to z-indexes
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial modal package with centered dialog primitives, token-based sizing, stories, and tests.

package/README.md

@@ -0,0 +1,63 @@
+# @edux-design/modals
+
+Centered modal primitives built on top of Radix Dialog and Edux design tokens.
+
+Exports:
+
+- `Modal`
+- `ModalTrigger`
+- `ModalClose`
+- `ModalPortal`
+- `ModalOverlay`
+- `ModalContent`
+- `ModalHeader`
+- `ModalBody`
+- `ModalFooter`
+- `ModalTitle`
+- `ModalDescription`
+
+## Usage
+
+```jsx
+import {
+  Modal,
+  ModalTrigger,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalClose,
+  ModalTitle,
+  ModalDescription,
+} from "@edux-design/modals";
+import { Button } from "@edux-design/buttons";
+
+export function PublishModal() {
+  return (
+    <Modal>
+      <ModalTrigger asChild>
+        <Button variant="primary">Open Modal</Button>
+      </ModalTrigger>
+      <ModalContent size="medium">
+        <ModalHeader>
+          <ModalTitle>Publish changes</ModalTitle>
+          <ModalDescription>
+            Review content before making it visible.
+          </ModalDescription>
+        </ModalHeader>
+        <ModalBody>
+          <p>Modal body content.</p>
+        </ModalBody>
+        <ModalFooter>
+          <ModalClose asChild>
+            <Button variant="secondary">Cancel</Button>
+          </ModalClose>
+          <Button variant="primary">Publish</Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  );
+}
+```
+
+`ModalContent` accepts `size`, `backdropProps`, `backDropProps`, `className`, and `contentProps`. Storybook examples live in `src/demos/Modal.stories.jsx`.

package/dist/index.js

@@ -0,0 +1,219 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  Modal: () => Modal,
+  ModalBody: () => ModalBody,
+  ModalClose: () => ModalClose,
+  ModalContent: () => ModalContent,
+  ModalDescription: () => ModalDescription,
+  ModalFooter: () => ModalFooter,
+  ModalHeader: () => ModalHeader,
+  ModalOverlay: () => ModalOverlay,
+  ModalPortal: () => ModalPortal,
+  ModalTitle: () => ModalTitle,
+  ModalTrigger: () => ModalTrigger
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/elements/Modal.jsx
+var import_react = __toESM(require("react"));
+var DialogPrimitive = __toESM(require("@radix-ui/react-dialog"));
+var import_utils = require("@edux-design/utils");
+var MODAL_OVERLAY_Z_INDEX = 2147483645;
+var MODAL_CONTENT_Z_INDEX = 2147483646;
+var getSizeClasses = (size) => {
+  switch (size) {
+    case "small":
+      return "w-[min(92vw,420px)]";
+    case "large":
+      return "w-[min(92vw,840px)]";
+    case "full":
+      return "w-[min(96vw,1200px)] h-[min(92vh,900px)]";
+    case "medium":
+    default:
+      return "w-[min(92vw,640px)]";
+  }
+};
+var Modal = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+  onOpen,
+  onClose,
+  children,
+  ...props
+}) => {
+  const handleOpenChange = (0, import_react.useCallback)(
+    (nextOpen) => {
+      onOpenChange == null ? void 0 : onOpenChange(nextOpen);
+      if (nextOpen) {
+        onOpen == null ? void 0 : onOpen();
+        return;
+      }
+      onClose == null ? void 0 : onClose();
+    },
+    [onClose, onOpen, onOpenChange]
+  );
+  return /* @__PURE__ */ import_react.default.createElement(
+    DialogPrimitive.Root,
+    {
+      open,
+      defaultOpen,
+      onOpenChange: handleOpenChange,
+      ...props
+    },
+    children
+  );
+};
+var ModalTrigger = DialogPrimitive.Trigger;
+var ModalClose = DialogPrimitive.Close;
+var ModalPortal = DialogPrimitive.Portal;
+var ModalOverlay = (0, import_react.forwardRef)(
+  ({ className, style, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+    DialogPrimitive.Overlay,
+    {
+      ref,
+      className: (0, import_utils.cx)(
+        "fixed inset-0 bg-bg-focus-overlay opacity-70",
+        "data-[state=open]:animate-drawer-fade-in data-[state=closed]:animate-drawer-fade-out",
+        className
+      ),
+      style: { zIndex: MODAL_OVERLAY_Z_INDEX, ...style },
+      ...props
+    }
+  )
+);
+ModalOverlay.displayName = "ModalOverlay";
+var ModalContent = (0, import_react.forwardRef)(
+  ({
+    children,
+    size = "medium",
+    className,
+    style,
+    backdropProps,
+    backDropProps,
+    contentProps = {},
+    ...restProps
+  }, ref) => {
+    const resolvedBackdropProps = backdropProps ?? backDropProps ?? {};
+    return /* @__PURE__ */ import_react.default.createElement(ModalPortal, null, /* @__PURE__ */ import_react.default.createElement(
+      ModalOverlay,
+      {
+        ...resolvedBackdropProps,
+        className: (0, import_utils.cx)(resolvedBackdropProps.className),
+        style: { ...resolvedBackdropProps.style }
+      }
+    ), /* @__PURE__ */ import_react.default.createElement(
+      DialogPrimitive.Content,
+      {
+        ref,
+        className: (0, import_utils.cx)(
+          "fixed left-1/2 top-1/2 max-h-[92vh] -translate-x-1/2 -translate-y-1/2",
+          "bg-bg-base text-fg-base shadow-xl outline-none rounded-2xl border border-border-subtle",
+          "flex flex-col overflow-hidden",
+          "data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out",
+          getSizeClasses(size),
+          className
+        ),
+        style: { zIndex: MODAL_CONTENT_Z_INDEX, ...style },
+        ...contentProps,
+        ...restProps
+      },
+      children
+    ));
+  }
+);
+ModalContent.displayName = "ModalContent";
+var ModalHeader = (0, import_react.forwardRef)(({ className, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+  "div",
+  {
+    ref,
+    className: (0, import_utils.cx)(
+      "flex flex-col gap-4 px-20 py-16 border-b border-border-subtle",
+      className
+    ),
+    ...props
+  }
+));
+ModalHeader.displayName = "ModalHeader";
+var ModalBody = (0, import_react.forwardRef)(({ className, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+  "div",
+  {
+    ref,
+    className: (0, import_utils.cx)("flex-1 overflow-auto px-20 py-16", className),
+    ...props
+  }
+));
+ModalBody.displayName = "ModalBody";
+var ModalFooter = (0, import_react.forwardRef)(({ className, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+  "div",
+  {
+    ref,
+    className: (0, import_utils.cx)(
+      "flex items-center justify-end gap-8 px-20 py-16 border-t border-border-subtle",
+      className
+    ),
+    ...props
+  }
+));
+ModalFooter.displayName = "ModalFooter";
+var ModalTitle = (0, import_react.forwardRef)(({ className, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+  DialogPrimitive.Title,
+  {
+    ref,
+    className: (0, import_utils.cx)("text-lg font-semibold text-fg-base", className),
+    ...props
+  }
+));
+ModalTitle.displayName = "ModalTitle";
+var ModalDescription = (0, import_react.forwardRef)(({ className, ...props }, ref) => /* @__PURE__ */ import_react.default.createElement(
+  DialogPrimitive.Description,
+  {
+    ref,
+    className: (0, import_utils.cx)("text-sm text-fg-subtle", className),
+    ...props
+  }
+));
+ModalDescription.displayName = "ModalDescription";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Modal,
+  ModalBody,
+  ModalClose,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalOverlay,
+  ModalPortal,
+  ModalTitle,
+  ModalTrigger
+});

package/dist/index.mjs

@@ -0,0 +1,173 @@
+// src/elements/Modal.jsx
+import React, { forwardRef, useCallback } from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { cx } from "@edux-design/utils";
+var MODAL_OVERLAY_Z_INDEX = 2147483645;
+var MODAL_CONTENT_Z_INDEX = 2147483646;
+var getSizeClasses = (size) => {
+  switch (size) {
+    case "small":
+      return "w-[min(92vw,420px)]";
+    case "large":
+      return "w-[min(92vw,840px)]";
+    case "full":
+      return "w-[min(96vw,1200px)] h-[min(92vh,900px)]";
+    case "medium":
+    default:
+      return "w-[min(92vw,640px)]";
+  }
+};
+var Modal = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+  onOpen,
+  onClose,
+  children,
+  ...props
+}) => {
+  const handleOpenChange = useCallback(
+    (nextOpen) => {
+      onOpenChange == null ? void 0 : onOpenChange(nextOpen);
+      if (nextOpen) {
+        onOpen == null ? void 0 : onOpen();
+        return;
+      }
+      onClose == null ? void 0 : onClose();
+    },
+    [onClose, onOpen, onOpenChange]
+  );
+  return /* @__PURE__ */ React.createElement(
+    DialogPrimitive.Root,
+    {
+      open,
+      defaultOpen,
+      onOpenChange: handleOpenChange,
+      ...props
+    },
+    children
+  );
+};
+var ModalTrigger = DialogPrimitive.Trigger;
+var ModalClose = DialogPrimitive.Close;
+var ModalPortal = DialogPrimitive.Portal;
+var ModalOverlay = forwardRef(
+  ({ className, style, ...props }, ref) => /* @__PURE__ */ React.createElement(
+    DialogPrimitive.Overlay,
+    {
+      ref,
+      className: cx(
+        "fixed inset-0 bg-bg-focus-overlay opacity-70",
+        "data-[state=open]:animate-drawer-fade-in data-[state=closed]:animate-drawer-fade-out",
+        className
+      ),
+      style: { zIndex: MODAL_OVERLAY_Z_INDEX, ...style },
+      ...props
+    }
+  )
+);
+ModalOverlay.displayName = "ModalOverlay";
+var ModalContent = forwardRef(
+  ({
+    children,
+    size = "medium",
+    className,
+    style,
+    backdropProps,
+    backDropProps,
+    contentProps = {},
+    ...restProps
+  }, ref) => {
+    const resolvedBackdropProps = backdropProps ?? backDropProps ?? {};
+    return /* @__PURE__ */ React.createElement(ModalPortal, null, /* @__PURE__ */ React.createElement(
+      ModalOverlay,
+      {
+        ...resolvedBackdropProps,
+        className: cx(resolvedBackdropProps.className),
+        style: { ...resolvedBackdropProps.style }
+      }
+    ), /* @__PURE__ */ React.createElement(
+      DialogPrimitive.Content,
+      {
+        ref,
+        className: cx(
+          "fixed left-1/2 top-1/2 max-h-[92vh] -translate-x-1/2 -translate-y-1/2",
+          "bg-bg-base text-fg-base shadow-xl outline-none rounded-2xl border border-border-subtle",
+          "flex flex-col overflow-hidden",
+          "data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out",
+          getSizeClasses(size),
+          className
+        ),
+        style: { zIndex: MODAL_CONTENT_Z_INDEX, ...style },
+        ...contentProps,
+        ...restProps
+      },
+      children
+    ));
+  }
+);
+ModalContent.displayName = "ModalContent";
+var ModalHeader = forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ React.createElement(
+  "div",
+  {
+    ref,
+    className: cx(
+      "flex flex-col gap-4 px-20 py-16 border-b border-border-subtle",
+      className
+    ),
+    ...props
+  }
+));
+ModalHeader.displayName = "ModalHeader";
+var ModalBody = forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ React.createElement(
+  "div",
+  {
+    ref,
+    className: cx("flex-1 overflow-auto px-20 py-16", className),
+    ...props
+  }
+));
+ModalBody.displayName = "ModalBody";
+var ModalFooter = forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ React.createElement(
+  "div",
+  {
+    ref,
+    className: cx(
+      "flex items-center justify-end gap-8 px-20 py-16 border-t border-border-subtle",
+      className
+    ),
+    ...props
+  }
+));
+ModalFooter.displayName = "ModalFooter";
+var ModalTitle = forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ React.createElement(
+  DialogPrimitive.Title,
+  {
+    ref,
+    className: cx("text-lg font-semibold text-fg-base", className),
+    ...props
+  }
+));
+ModalTitle.displayName = "ModalTitle";
+var ModalDescription = forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ React.createElement(
+  DialogPrimitive.Description,
+  {
+    ref,
+    className: cx("text-sm text-fg-subtle", className),
+    ...props
+  }
+));
+ModalDescription.displayName = "ModalDescription";
+export {
+  Modal,
+  ModalBody,
+  ModalClose,
+  ModalContent,
+  ModalDescription,
+  ModalFooter,
+  ModalHeader,
+  ModalOverlay,
+  ModalPortal,
+  ModalTitle,
+  ModalTrigger
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@edux-design/modals",
+  "version": "0.1.1",
+  "private": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "build": "tsup src/index.js --format esm,cjs --external react,react-dom,@edux-design/utils,@radix-ui/react-dialog",
+    "dev": "tsup src/index.js --watch --format esm,cjs --external react,react-dom,@edux-design/utils,@radix-ui/react-dialog",
+    "generate:component": "turbo gen react-component",
+    "check-types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "@edux-design/utils": "*",
+    "@radix-ui/react-dialog": "1.1.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "tailwindcss": "^4.1.12",
+    "postcss": "^8.5.6",
+    "tsup": "^8.5.0",
+    "@tailwindcss/cli": "^4.1.12",
+    "@tailwindcss/postcss": "^4.1.12"
+  }
+}

package/src/demos/Modal.stories.jsx

@@ -0,0 +1,168 @@
+import React, { useState } from "react";
+import {
+  Modal,
+  ModalTrigger,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalClose,
+  ModalTitle,
+  ModalDescription,
+} from "../index";
+import { Button } from "@edux-design/buttons";
+
+const meta = {
+  title: "Components/Modal",
+  component: Modal,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+Centered **Modal** built on Radix Dialog primitives.
+
+Use for confirmations, forms, and focused blocking workflows.
+        `,
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["small", "medium", "large", "full"],
+      description: "Width preset for the modal content.",
+      table: { defaultValue: { summary: "medium" } },
+    },
+  },
+};
+
+export default meta;
+
+export const Basic = {
+  render: (args) => (
+    <Modal>
+      <ModalTrigger asChild>
+        <Button variant="primary">Open Modal</Button>
+      </ModalTrigger>
+      <ModalContent {...args}>
+        <ModalHeader>
+          <ModalTitle>Publish changes</ModalTitle>
+          <ModalDescription>
+            Review your changes before making them visible to learners.
+          </ModalDescription>
+        </ModalHeader>
+        <ModalBody>
+          <p className="text-sm text-fg-subtle">
+            This modal supports title, description, body, and footer regions.
+          </p>
+        </ModalBody>
+        <ModalFooter>
+          <ModalClose asChild>
+            <Button variant="secondary">Cancel</Button>
+          </ModalClose>
+          <Button variant="primary">Publish</Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  ),
+  args: {
+    size: "medium",
+  },
+};
+
+export const Controlled = {
+  render: (args) => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <Modal open={open} onOpenChange={setOpen}>
+        <ModalTrigger asChild>
+          <Button variant="primary">
+            {open ? "Close Modal" : "Open Modal"}
+          </Button>
+        </ModalTrigger>
+        <ModalContent {...args}>
+          <ModalHeader>
+            <ModalTitle>Controlled modal</ModalTitle>
+            <ModalDescription>
+              State is managed externally via open and onOpenChange.
+            </ModalDescription>
+          </ModalHeader>
+          <ModalBody>
+            <p className="text-sm text-fg-subtle">
+              Use this variant when the parent controls the workflow.
+            </p>
+          </ModalBody>
+          <ModalFooter>
+            <Button variant="bare" onClick={() => setOpen(false)}>
+              Dismiss
+            </Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    );
+  },
+  args: {
+    size: "medium",
+  },
+};
+
+export const Sizes = {
+  render: () => (
+    <div className="flex flex-wrap gap-12">
+      {["small", "medium", "large", "full"].map((size) => (
+        <Modal key={size}>
+          <ModalTrigger asChild>
+            <Button variant="secondary">Size: {size}</Button>
+          </ModalTrigger>
+          <ModalContent size={size}>
+            <ModalHeader>
+              <ModalTitle>{size} modal</ModalTitle>
+              <ModalDescription>
+                Demonstrates the {size} content width preset.
+              </ModalDescription>
+            </ModalHeader>
+            <ModalBody>
+              <p className="text-sm text-fg-subtle">
+                These presets use existing spacing, border, shadow, and
+                foreground/background tokens.
+              </p>
+            </ModalBody>
+          </ModalContent>
+        </Modal>
+      ))}
+    </div>
+  ),
+};
+
+export const CustomBackdrop = {
+  render: (args) => (
+    <Modal>
+      <ModalTrigger asChild>
+        <Button variant="primary">Open With Backdrop</Button>
+      </ModalTrigger>
+      <ModalContent
+        {...args}
+        backdropProps={{
+          className: "bg-bg-primary-subtle opacity-80",
+        }}
+      >
+        <ModalHeader>
+          <ModalTitle>Custom backdrop</ModalTitle>
+          <ModalDescription>
+            Backdrop styles can be customized via backdropProps.
+          </ModalDescription>
+        </ModalHeader>
+        <ModalBody>
+          <p className="text-sm text-fg-subtle">
+            Override color and opacity without changing the modal surface.
+          </p>
+        </ModalBody>
+      </ModalContent>
+    </Modal>
+  ),
+  args: {
+    size: "medium",
+  },
+};

package/src/elements/Modal.jsx

@@ -0,0 +1,176 @@
+import React, { forwardRef, useCallback } from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { cx } from "@edux-design/utils";
+
+const MODAL_OVERLAY_Z_INDEX = 2147483645;
+const MODAL_CONTENT_Z_INDEX = 2147483646;
+
+const getSizeClasses = (size) => {
+  switch (size) {
+    case "small":
+      return "w-[min(92vw,420px)]";
+    case "large":
+      return "w-[min(92vw,840px)]";
+    case "full":
+      return "w-[min(96vw,1200px)] h-[min(92vh,900px)]";
+    case "medium":
+    default:
+      return "w-[min(92vw,640px)]";
+  }
+};
+
+export const Modal = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+  onOpen,
+  onClose,
+  children,
+  ...props
+}) => {
+  const handleOpenChange = useCallback(
+    (nextOpen) => {
+      onOpenChange?.(nextOpen);
+      if (nextOpen) {
+        onOpen?.();
+        return;
+      }
+      onClose?.();
+    },
+    [onClose, onOpen, onOpenChange]
+  );
+
+  return (
+    <DialogPrimitive.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={handleOpenChange}
+      {...props}
+    >
+      {children}
+    </DialogPrimitive.Root>
+  );
+};
+
+export const ModalTrigger = DialogPrimitive.Trigger;
+export const ModalClose = DialogPrimitive.Close;
+export const ModalPortal = DialogPrimitive.Portal;
+
+export const ModalOverlay = forwardRef(
+  ({ className, style, ...props }, ref) => (
+    <DialogPrimitive.Overlay
+      ref={ref}
+      className={cx(
+        "fixed inset-0 bg-bg-focus-overlay opacity-70",
+        "data-[state=open]:animate-drawer-fade-in data-[state=closed]:animate-drawer-fade-out",
+        className
+      )}
+      style={{ zIndex: MODAL_OVERLAY_Z_INDEX, ...style }}
+      {...props}
+    />
+  )
+);
+
+ModalOverlay.displayName = "ModalOverlay";
+
+export const ModalContent = forwardRef(
+  (
+    {
+      children,
+      size = "medium",
+      className,
+      style,
+      backdropProps,
+      backDropProps,
+      contentProps = {},
+      ...restProps
+    },
+    ref
+  ) => {
+    const resolvedBackdropProps = backdropProps ?? backDropProps ?? {};
+
+    return (
+      <ModalPortal>
+        <ModalOverlay
+          {...resolvedBackdropProps}
+          className={cx(resolvedBackdropProps.className)}
+          style={{ ...resolvedBackdropProps.style }}
+        />
+        <DialogPrimitive.Content
+          ref={ref}
+          className={cx(
+            "fixed left-1/2 top-1/2 max-h-[92vh] -translate-x-1/2 -translate-y-1/2",
+            "bg-bg-base text-fg-base shadow-xl outline-none rounded-2xl border border-border-subtle",
+            "flex flex-col overflow-hidden",
+            "data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out",
+            getSizeClasses(size),
+            className
+          )}
+          style={{ zIndex: MODAL_CONTENT_Z_INDEX, ...style }}
+          {...contentProps}
+          {...restProps}
+        >
+          {children}
+        </DialogPrimitive.Content>
+      </ModalPortal>
+    );
+  }
+);
+
+ModalContent.displayName = "ModalContent";
+
+export const ModalHeader = forwardRef(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cx(
+      "flex flex-col gap-4 px-20 py-16 border-b border-border-subtle",
+      className
+    )}
+    {...props}
+  />
+));
+
+ModalHeader.displayName = "ModalHeader";
+
+export const ModalBody = forwardRef(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cx("flex-1 overflow-auto px-20 py-16", className)}
+    {...props}
+  />
+));
+
+ModalBody.displayName = "ModalBody";
+
+export const ModalFooter = forwardRef(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cx(
+      "flex items-center justify-end gap-8 px-20 py-16 border-t border-border-subtle",
+      className
+    )}
+    {...props}
+  />
+));
+
+ModalFooter.displayName = "ModalFooter";
+
+export const ModalTitle = forwardRef(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cx("text-lg font-semibold text-fg-base", className)}
+    {...props}
+  />
+));
+
+ModalTitle.displayName = "ModalTitle";
+
+export const ModalDescription = forwardRef(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cx("text-sm text-fg-subtle", className)}
+    {...props}
+  />
+));
+
+ModalDescription.displayName = "ModalDescription";

package/src/elements/Modal.test.jsx

@@ -0,0 +1,111 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import {
+  Modal,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalTitle,
+  ModalDescription,
+} from "./Modal";
+
+let lastRootProps;
+
+vi.mock("@radix-ui/react-dialog", () => {
+  const Passthrough = ({ children, ...props }) => (
+    <div {...props}>{children}</div>
+  );
+  const Buttonish = ({ children, ...props }) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  );
+  const Content = React.forwardRef((props, ref) => (
+    <div ref={ref} data-testid="radix-content" {...props} />
+  ));
+  Content.displayName = "RadixContent";
+  const Overlay = React.forwardRef((props, ref) => (
+    <div ref={ref} data-testid="radix-overlay" {...props} />
+  ));
+  Overlay.displayName = "RadixOverlay";
+  const Root = ({ children, ...props }) => {
+    lastRootProps = props;
+    return <div {...props}>{children}</div>;
+  };
+
+  return {
+    Root,
+    Trigger: Buttonish,
+    Portal: Passthrough,
+    Overlay,
+    Content,
+    Close: Buttonish,
+    Title: Passthrough,
+    Description: Passthrough,
+  };
+});
+
+describe("ModalContent", () => {
+  it("renders overlay with default styling and supports custom backdrop props", () => {
+    render(
+      <Modal>
+        <ModalContent
+          size="large"
+          backdropProps={{ className: "custom-backdrop" }}
+        >
+          Body
+        </ModalContent>
+      </Modal>
+    );
+
+    const overlay = screen.getByTestId("radix-overlay");
+    expect(overlay).toHaveClass("bg-bg-focus-overlay");
+    expect(overlay).toHaveClass("custom-backdrop");
+    expect(overlay).toHaveStyle({ zIndex: "2147483645" });
+
+    const content = screen.getByTestId("radix-content");
+    expect(content).toHaveClass("left-1/2");
+    expect(content).toHaveClass("w-[min(92vw,840px)]");
+    expect(content).toHaveStyle({ zIndex: "2147483646" });
+  });
+
+  it("composes header, body, footer, title, and description sections", () => {
+    render(
+      <Modal>
+        <ModalContent>
+          <ModalHeader>
+            <ModalTitle>Header</ModalTitle>
+            <ModalDescription>Details</ModalDescription>
+          </ModalHeader>
+          <ModalBody>Body</ModalBody>
+          <ModalFooter>Footer</ModalFooter>
+        </ModalContent>
+      </Modal>
+    );
+
+    expect(screen.getByText("Header")).toHaveClass("font-semibold");
+    expect(screen.getByText("Details")).toHaveClass("text-fg-subtle");
+    expect(screen.getByText("Body")).toHaveClass("overflow-auto");
+    expect(screen.getByText("Footer")).toHaveClass("border-t");
+  });
+});
+
+describe("Modal", () => {
+  it("fires onOpen and onClose from onOpenChange", () => {
+    const onOpen = vi.fn();
+    const onClose = vi.fn();
+
+    render(
+      <Modal onOpen={onOpen} onClose={onClose}>
+        <ModalContent>Body</ModalContent>
+      </Modal>
+    );
+
+    lastRootProps.onOpenChange(true);
+    lastRootProps.onOpenChange(false);
+
+    expect(onOpen).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.js

@@ -0,0 +1,13 @@
+export {
+  Modal,
+  ModalTrigger,
+  ModalClose,
+  ModalPortal,
+  ModalOverlay,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalTitle,
+  ModalDescription,
+} from "./elements/Modal";