@lostgradient/cinder 0.1.0

package/src/components/modal/modal.css

@@ -0,0 +1,191 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * MODAL
+ * ======================================== */
+
+  .cinder-modal {
+    /* Reset browser's default <dialog> styles */
+    margin: auto;
+    padding: 0;
+    border: none;
+    border-radius: var(--cinder-radius-lg);
+    background: transparent;
+    color: var(--cinder-text);
+    max-width: min(90vw, 32rem);
+    width: 100%;
+
+    /* Prevent the panel from touching viewport edges on small screens */
+    max-height: calc(100dvh - var(--cinder-space-8));
+    overflow: hidden;
+  }
+
+  /* Backdrop — native <dialog>::backdrop is controlled by the UA */
+  .cinder-modal::backdrop {
+    background: var(--cinder-overlay-backdrop);
+    backdrop-filter: blur(var(--cinder-overlay-blur));
+  }
+
+  /* ----------------------------------------
+ * Panel (the visible card inside the dialog)
+ * ---------------------------------------- */
+
+  .cinder-modal__panel {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    background: var(--cinder-surface-raised);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-lg);
+    box-shadow: var(--cinder-shadow-lg);
+    max-height: inherit;
+    overflow: hidden;
+  }
+
+  /* ----------------------------------------
+ * Header
+ * ---------------------------------------- */
+
+  .cinder-modal__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-4);
+    /* Reserve trailing inline space so the title doesn't run under the
+     absolute-positioned close button. */
+    padding-block: var(--cinder-space-5);
+    padding-inline-start: var(--cinder-space-6);
+    padding-inline-end: calc(var(--cinder-space-6) + 2rem);
+    border-block-end: 1px solid var(--cinder-border);
+    flex-shrink: 0;
+  }
+
+  .cinder-modal__title {
+    margin: 0;
+    font-size: var(--cinder-text-lg);
+    font-weight: var(--cinder-font-semibold);
+    line-height: var(--cinder-leading-snug);
+    color: var(--cinder-text);
+  }
+
+  /* ----------------------------------------
+ * Close button
+ * ---------------------------------------- */
+
+  .cinder-modal__close {
+    /* Rendered last in DOM order so the close button isn't the first focusable
+     element on dialog open — but visually positioned in the header corner. */
+    position: absolute;
+    inset-block-start: var(--cinder-space-3);
+    inset-inline-end: var(--cinder-space-3);
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 2rem;
+    height: 2rem;
+    padding: var(--cinder-space-1);
+
+    border-radius: var(--cinder-radius-md);
+    border: none;
+    background: transparent;
+    color: var(--cinder-text-muted);
+    cursor: pointer;
+
+    transition:
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      box-shadow var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .cinder-modal__close:hover {
+      background: color-mix(in oklch, currentColor, transparent 85%);
+      color: var(--cinder-text);
+    }
+  }
+
+  .cinder-modal__close:focus-visible {
+    /* The close button sits in the panel corner, and the panel has
+     `overflow: hidden`. An outset box-shadow ring would be clipped there, so
+     paint an INSET ring (Strategy B-inset) entirely within the button's own
+     border box. The transparent outline placeholder reserves the channel the
+     forced-colors fallback repaints (WCAG 2.4.7). */
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width)
+      var(--_cinder-modal-close-ring, var(--cinder-ring-color));
+  }
+
+  @media (forced-colors: active) {
+    .cinder-modal__close:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+    }
+  }
+
+  .cinder-modal__close-icon {
+    width: 1.25rem;
+    height: 1.25rem;
+  }
+
+  /* ----------------------------------------
+ * Body
+ * ---------------------------------------- */
+
+  .cinder-modal__body {
+    flex: 1;
+    overflow-y: auto;
+    padding: var(--cinder-space-6);
+    overscroll-behavior: contain;
+    scrollbar-gutter: stable;
+    /* The body container is focused on open (tabindex=-1) when the dialog has
+     no autofocus target. The ring is hidden because focus arrived
+     programmatically — pressing Tab forward will move into real content. */
+    outline: none;
+  }
+
+  .cinder-modal__body[data-cinder-overflows] {
+    mask-image: linear-gradient(to bottom, black calc(100% - 1.5rem), transparent);
+    mask-size: 100% 100%;
+    mask-repeat: no-repeat;
+    -webkit-mask-image: linear-gradient(to bottom, black calc(100% - 1.5rem), transparent);
+    -webkit-mask-size: 100% 100%;
+    -webkit-mask-repeat: no-repeat;
+  }
+
+  /* ----------------------------------------
+ * Footer
+ * ---------------------------------------- */
+
+  .cinder-modal__footer {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: var(--cinder-space-3);
+    padding: var(--cinder-space-4) var(--cinder-space-6);
+    border-block-start: 1px solid var(--cinder-border);
+    flex-shrink: 0;
+  }
+
+  /* ----------------------------------------
+ * Reduced motion
+ * ---------------------------------------- */
+
+  @media (prefers-reduced-motion: no-preference) {
+    .cinder-modal {
+      animation: cinder-modal-enter var(--cinder-duration-normal) var(--cinder-ease-spring) forwards;
+    }
+
+    @keyframes cinder-modal-enter {
+      from {
+        opacity: 0;
+        translate: 0 -0.5rem;
+      }
+      to {
+        opacity: 1;
+        translate: 0 0;
+      }
+    }
+  }
+}

package/src/components/modal/modal.examples.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "modal",
+  "import": "@lostgradient/cinder/modal",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic modal",
+      "description": "A modal used as a generic content shell — in this case an invite form with structured fields.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Input } from '@lostgradient/cinder/input';\n  import { Modal } from '@lostgradient/cinder/modal';\n\n  let open = $state(false);\n  let triggerRef: HTMLElement | null = $state(null);\n  let email = $state('');\n  let name = $state('');\n\n  function handleSend() {\n    open = false;\n  }\n</script>\n\n<Button\n  label=\"Invite teammate\"\n  onclick={(event) => {\n    triggerRef = event.currentTarget;\n    open = true;\n  }}\n/>\n\n<Modal bind:open title=\"Invite teammate\" {triggerRef}>\n  <div style=\"display: grid; gap: 1rem;\">\n    <Input id=\"invite-name\" label=\"Full name\" placeholder=\"Alex Kim\" bind:value={name} autofocus />\n    <Input\n      id=\"invite-email\"\n      label=\"Email address\"\n      type=\"email\"\n      placeholder=\"alex@example.com\"\n      bind:value={email}\n    />\n  </div>\n\n  {#snippet footer()}\n    <div style=\"display: flex; gap: 0.5rem; justify-content: flex-end;\">\n      <Button variant=\"secondary\" label=\"Cancel\" onclick={() => (open = false)} />\n      <Button variant=\"primary\" label=\"Send invite\" onclick={handleSend} />\n    </div>\n  {/snippet}\n</Modal>\n"
+    },
+    {
+      "id": "overflowing",
+      "title": "Overflowing modal",
+      "description": "A modal body with enough content to scroll.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Modal } from '@lostgradient/cinder/modal';\n\n  let open = $state(false);\n  let longContent = $state(true);\n  let triggerRef: HTMLElement | null = $state(null);\n\n  const sections = Array.from({ length: 12 }, (_, index) => ({\n    id: `section-${index + 1}`,\n    title: `Review section ${index + 1}`,\n    body: 'Operational notes, approval context, and supporting detail for the current workflow.',\n  }));\n</script>\n\n<div style=\"display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: center;\">\n  <Button\n    label=\"Open modal\"\n    onclick={(event) => {\n      triggerRef = event.currentTarget as HTMLElement;\n      open = true;\n    }}\n  />\n  <Button\n    label={longContent ? 'Use short content' : 'Use long content'}\n    variant=\"secondary\"\n    onclick={() => (longContent = !longContent)}\n  />\n</div>\n\n<Modal bind:open title=\"Release checklist\" {triggerRef}>\n  {#if longContent}\n    <div style=\"display: grid; gap: 1rem;\">\n      {#each sections as section (section.id)}\n        <section>\n          <h3 style=\"margin: 0 0 0.25rem; font-size: var(--cinder-text-base);\">\n            {section.title}\n          </h3>\n          <p style=\"margin: 0; color: var(--cinder-text-muted);\">{section.body}</p>\n        </section>\n      {/each}\n    </div>\n  {:else}\n    <p style=\"margin: 0;\">This short body should fit without a scroll fade.</p>\n  {/if}\n\n  {#snippet footer()}\n    <Button label=\"Close\" onclick={() => (open = false)} />\n  {/snippet}\n</Modal>\n"
+    },
+    {
+      "id": "with-form",
+      "title": "Modal with form",
+      "description": "A modal whose first input carries autofocus; the native dialog focuses it on open.",
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { Input } from '@lostgradient/cinder/input';\n  import { Modal } from '@lostgradient/cinder/modal';\n  let open = $state(false);\n  let name = $state('');\n  let triggerRef: HTMLElement | null = $state(null);\n</script>\n\n<Button\n  label=\"Rename item\"\n  onclick={(event) => {\n    triggerRef = event.currentTarget;\n    open = true;\n  }}\n/>\n\n<Modal bind:open title=\"Rename item\" {triggerRef}>\n  <Input id=\"modal-name\" bind:value={name} label=\"New name\" placeholder=\"Enter a name…\" autofocus />\n  {#snippet footer()}\n    <div style=\"display: flex; gap: 0.5rem; justify-content: flex-end;\">\n      <Button variant=\"secondary\" label=\"Cancel\" onclick={() => (open = false)} />\n      <Button variant=\"primary\" label=\"Save\" onclick={() => (open = false)} />\n    </div>\n  {/snippet}\n</Modal>\n"
+    }
+  ]
+}

package/src/components/modal/modal.fixture.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+  import { Modal } from './index.ts';
+
+  type FixtureProps = {
+    describedById?: string;
+    open?: boolean;
+    title?: string;
+  };
+
+  let { describedById, open = true, title = 'Fixture dialog' }: FixtureProps = $props();
+  let modalOpen = $state(open);
+  let triggerRef: HTMLButtonElement | null = $state(null);
+</script>
+
+<div class="modal-fixture">
+  <button bind:this={triggerRef} class="modal-fixture__trigger" type="button">
+    Open fixture modal
+  </button>
+
+  {#if describedById}
+    <Modal bind:open={modalOpen} {title} {triggerRef} {describedById}>
+      <p id={describedById}>
+        This dialog includes a description so aria-describedby can be captured in the visual
+        fixture.
+      </p>
+
+      {#snippet footer()}
+        <button class="modal-fixture__action" type="button" onclick={() => (modalOpen = false)}>
+          Cancel
+        </button>
+        <button
+          class="modal-fixture__action modal-fixture__action--primary"
+          type="button"
+          onclick={() => (modalOpen = false)}
+        >
+          Save changes
+        </button>
+      {/snippet}
+    </Modal>
+  {:else}
+    <Modal bind:open={modalOpen} {title} {triggerRef}>
+      <p>This dialog body is supplied by the host fixture.</p>
+
+      {#snippet footer()}
+        <button class="modal-fixture__action" type="button" onclick={() => (modalOpen = false)}>
+          Cancel
+        </button>
+        <button
+          class="modal-fixture__action modal-fixture__action--primary"
+          type="button"
+          onclick={() => (modalOpen = false)}
+        >
+          Save changes
+        </button>
+      {/snippet}
+    </Modal>
+  {/if}
+</div>
+
+<style>
+  .modal-fixture {
+    display: grid;
+    min-block-size: 12rem;
+    place-items: start;
+  }
+
+  .modal-fixture__trigger {
+    border: 1px solid var(--cinder-border);
+    border-radius: 0.375rem;
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    font: inherit;
+    padding: 0.5rem 0.75rem;
+  }
+
+  .modal-fixture__action {
+    border: 1px solid var(--cinder-border);
+    border-radius: 0.375rem;
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    font: inherit;
+    padding: 0.5rem 0.75rem;
+  }
+
+  .modal-fixture__action--primary {
+    background: var(--cinder-accent);
+    color: var(--cinder-accent-contrast);
+  }
+</style>

package/src/components/modal/modal.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "open": {
+      "type": "boolean"
+    },
+    "title": {
+      "type": "string"
+    },
+    "dismissOnBackdropClick": {
+      "type": "boolean"
+    },
+    "dismissOnEscape": {
+      "type": "boolean"
+    },
+    "showCloseButton": {
+      "type": "boolean"
+    },
+    "class": {
+      "type": "string"
+    },
+    "role": {
+      "enum": ["dialog", "alertdialog"]
+    },
+    "describedById": {
+      "type": "string",
+      "description": "When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["open", "title"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "footer",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "ondismiss",
+        "reason": "function-or-snippet"
+      },
+      {
+        "name": "triggerRef",
+        "reason": "unknown-shape"
+      }
+    ]
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "role": {
+            "const": "alertdialog"
+          }
+        },
+        "required": ["role"]
+      },
+      "then": {
+        "required": ["describedById"]
+      }
+    }
+  ]
+}

package/src/components/modal/modal.schema.ts

@@ -0,0 +1,8 @@
+import type { ComponentSchema } from '../../schema-types';
+
+// eslint-disable-next-line no-unsafe-type-assertion -- generated schema parsed from a build-validated JSON string; see generate-component-schema.ts.
+const schema = JSON.parse(
+  '{\n  "$schema": "https://json-schema.org/draft/2020-12/schema",\n  "type": "object",\n  "properties": {\n    "open": {\n      "type": "boolean"\n    },\n    "title": {\n      "type": "string"\n    },\n    "dismissOnBackdropClick": {\n      "type": "boolean"\n    },\n    "dismissOnEscape": {\n      "type": "boolean"\n    },\n    "showCloseButton": {\n      "type": "boolean"\n    },\n    "class": {\n      "type": "string"\n    },\n    "role": {\n      "enum": [\n        "dialog",\n        "alertdialog"\n      ]\n    },\n    "describedById": {\n      "type": "string",\n      "description": "When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only."\n    }\n  },\n  "additionalProperties": false,\n  "required": [\n    "open",\n    "title"\n  ],\n  "metadata": {\n    "unsupportedProps": [\n      {\n        "name": "children",\n        "reason": "function-or-snippet"\n      },\n      {\n        "name": "footer",\n        "reason": "function-or-snippet"\n      },\n      {\n        "name": "ondismiss",\n        "reason": "function-or-snippet"\n      },\n      {\n        "name": "triggerRef",\n        "reason": "unknown-shape"\n      }\n    ]\n  },\n  "allOf": [\n    {\n      "if": {\n        "properties": {\n          "role": {\n            "const": "alertdialog"\n          }\n        },\n        "required": [\n          "role"\n        ]\n      },\n      "then": {\n        "required": [\n          "describedById"\n        ]\n      }\n    }\n  ]\n}',
+) as ComponentSchema;
+
+export default schema;

package/src/components/modal/modal.svelte

@@ -0,0 +1,252 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category overlay
+   * @status stable
+   * @purpose Centered modal dialog shell built on the native dialog element with focus capture, restoration, and dismissal handling.
+   * @tag overlay
+   * @tag dialog
+   * @useWhen Presenting rich or structured content that requires user interaction before returning to the page — forms, multi-step wizards, detail views.
+   * @useWhen Collecting structured input (forms, multi-field workflows) inside an overlay.
+   * @avoidWhen Only a two-action confirm/cancel prompt is needed — use confirm-dialog instead.
+   * @avoidWhen An urgent blocking acknowledgement is needed — use alert-dialog instead.
+   * @avoidWhen Showing side-anchored navigation or settings — use a drawer instead.
+   * @avoidWhen Presenting a small contextual surface anchored to a trigger — use a popover or sheet instead.
+   * @related confirm-dialog, alert-dialog, drawer, sheet, popover
+   */
+  export type { ModalProps } from './modal.types.ts';
+</script>
+
+<script lang="ts">
+  import type { ModalProps } from './modal.types.ts';
+  import { onDestroy } from 'svelte';
+  import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
+  import { overflowFade } from '../../utilities/attachments.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import { restoreFocusTo } from '../../utilities/focus.ts';
+
+  const titleId = $props.id();
+
+  let {
+    open = $bindable(false),
+    title,
+    role = 'dialog',
+    dismissOnBackdropClick = true,
+    dismissOnEscape = true,
+    showCloseButton = true,
+    class: className,
+    children,
+    footer,
+    triggerRef = null,
+    describedById,
+    ondismiss,
+  }: ModalProps = $props();
+
+  let dialogElement: HTMLDialogElement | undefined = $state();
+  let bodyElement: HTMLDivElement | undefined = $state();
+  // `mounted` is false during SSR and becomes true after the first client-side effect.
+  // The dialog renders only when mounted (client) or when open (SSR with open=true).
+  // This keeps the <dialog> absent from SSR HTML when closed, while letting the client
+  // keep the element mounted so dialogElement.close() fires correctly.
+  let mounted = $state(false);
+  // Element that had focus before the dialog opened. Captured each time the dialog
+  // transitions from closed → open so focus can be restored to wherever the user
+  // came from, even if the consumer didn't supply an explicit `triggerRef`.
+  let capturedFocus: HTMLElement | null = null;
+  // Refcounted body scroll lock. Acquired when `open` transitions to true and
+  // released on close OR on destroy (defensive — both fire on close-then-unmount,
+  // and idempotence is guaranteed by checking `releaseBodyScrollLock !== null`).
+  let releaseBodyScrollLock: (() => void) | null = null;
+  // Escape-stack handle. Modal handles its own Escape via the native <dialog>
+  // `cancel` event, but pushing a no-op handler keeps non-dialog overlays
+  // above us from accidentally swallowing the keystroke (per OVERLAY-POLICY).
+  let releaseEscapeHandler: (() => void) | null = null;
+
+  function acquireLock() {
+    if (releaseBodyScrollLock !== null) return;
+    releaseBodyScrollLock = lockBodyScroll();
+  }
+
+  function releaseLock() {
+    releaseBodyScrollLock?.();
+    releaseBodyScrollLock = null;
+  }
+
+  function acquireEscapeHandler() {
+    if (releaseEscapeHandler !== null) return;
+    releaseEscapeHandler = pushEscapeHandler(() => {
+      // No-op: the native <dialog> cancel event handles ESC dismissal. We
+      // push this handler purely to participate in the escape-stack ordering
+      // so non-dialog overlays above us route their own ESC correctly.
+    });
+  }
+
+  function releaseEscape() {
+    releaseEscapeHandler?.();
+    releaseEscapeHandler = null;
+  }
+
+  const bodyOverflowFade = overflowFade();
+
+  $effect(() => {
+    mounted = true;
+  });
+
+  $effect(() => {
+    if (
+      role === 'alertdialog' &&
+      (dismissOnBackdropClick !== false || dismissOnEscape !== false || showCloseButton !== false)
+    ) {
+      devWarn(
+        '[cinder/Modal] role="alertdialog" requires dismissOnBackdropClick={false}, dismissOnEscape={false}, and showCloseButton={false}. ' +
+          'Without these, Escape or backdrop click can bypass the mandatory acknowledgement. ' +
+          'Use <AlertDialog> instead, or pass all three companion props explicitly.',
+      );
+    }
+  });
+
+  $effect(() => {
+    if (!dialogElement) return;
+    if (open && !dialogElement.open) {
+      capturedFocus = captureFocus();
+      dialogElement.showModal();
+      acquireLock();
+      acquireEscapeHandler();
+      // Initial focus strategy:
+      //   1. If a child carries `autofocus`, the native dialog already focused it.
+      //   2. Otherwise, focus the body container (tabindex=-1) so initial focus
+      //      lands on meaningful content rather than the close-X button — which
+      //      would otherwise be the first sequentially-focusable element.
+      // Check both the HTML attribute (set by static markup) and the DOM property
+      // (set by Svelte 5's $.autofocus() helper, which sets element.autofocus = true
+      // rather than the attribute). The attribute selector alone misses the Svelte case.
+      const hasExplicitAutofocus =
+        dialogElement.querySelector('[autofocus]') !== null ||
+        Array.from(dialogElement.querySelectorAll<HTMLElement>('*')).some(
+          (el) => el.autofocus === true,
+        );
+      if (!hasExplicitAutofocus && bodyElement) {
+        bodyElement.focus();
+      }
+    } else if (!open && dialogElement.open) {
+      // Only close if the dialog is actually open — close() throws InvalidStateError
+      // if called on a dialog that was never opened.
+      dialogElement.close();
+    }
+  });
+
+  function returnFocus() {
+    // Iterate the local candidate list; the first that passes the connection
+    // /ownership check wins. No fallback to document.body — if both candidates
+    // are gone, leave focus where the browser put it.
+    const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
+    for (const candidate of candidates) {
+      if (restoreFocusTo(candidate)) break;
+    }
+    capturedFocus = null;
+  }
+
+  // Single source of truth for all user-initiated dismissal paths: Escape, backdrop click,
+  // and the close-X button. State flips FIRST so a thrown callback does not leave the
+  // dialog open. Callbacks are not awaited; sync throws propagate to the caller.
+  function dismiss() {
+    open = false;
+    ondismiss?.();
+  }
+
+  function handleClose() {
+    // Fired on the native 'close' event — may be triggered by dismiss() (via dialogElement.close())
+    // or by parent-driven open = false. Only restores focus; does NOT call ondismiss here
+    // so parent-driven closes do not fire the callback.
+    open = false;
+    releaseLock();
+    releaseEscape();
+    returnFocus();
+  }
+
+  onDestroy(() => {
+    // Defensive — close-then-unmount and unmount-while-open both land here.
+    // The release functions are idempotent so a double-release is impossible.
+    releaseLock();
+    releaseEscape();
+  });
+
+  function handleBackdropClick(event: MouseEvent) {
+    if (dismissOnBackdropClick && event.target === dialogElement) {
+      dismiss();
+    }
+  }
+
+  function handleNativeCancel(event: Event) {
+    // Escape key fires the native 'cancel' event on <dialog>. We prevent the default
+    // so the browser doesn't close the dialog through its own mechanism — we route
+    // exclusively through dismiss() → open = false → $effect → dialogElement.close()
+    // → 'close' event → handleClose. This ensures exactly one close path for Escape.
+    event.preventDefault();
+    if (!dismissOnEscape) return;
+    dismiss();
+  }
+</script>
+
+{#if mounted || open}
+  <dialog
+    bind:this={dialogElement}
+    class={classNames('cinder-modal', className)}
+    {role}
+    aria-modal="true"
+    aria-labelledby={titleId}
+    {...describedById ? { 'aria-describedby': describedById } : {}}
+    onclose={handleClose}
+    onclick={handleBackdropClick}
+    oncancel={handleNativeCancel}
+  >
+    {#if open}
+      <div class="cinder-modal__panel">
+        <div class="cinder-modal__header">
+          <h2 id={titleId} class="cinder-modal__title">{title}</h2>
+        </div>
+
+        <div
+          bind:this={bodyElement}
+          class="cinder-modal__body"
+          tabindex="-1"
+          {@attach bodyOverflowFade}
+        >
+          {@render children()}
+        </div>
+
+        {#if footer}
+          <div class="cinder-modal__footer">
+            {@render footer()}
+          </div>
+        {/if}
+
+        <!--
+          Rendered last so tabbing forward from the panel leaves it last in
+          sequential focus order. CSS positions it visually in the corner.
+        -->
+        {#if showCloseButton}
+          <button
+            type="button"
+            class="cinder-modal__close"
+            aria-label="Close dialog"
+            onclick={dismiss}
+          >
+            <svg
+              class="cinder-modal__close-icon"
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 20 20"
+              fill="currentColor"
+              aria-hidden="true"
+            >
+              <path
+                d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z"
+              />
+            </svg>
+          </button>
+        {/if}
+      </div>
+    {/if}
+  </dialog>
+{/if}

package/src/components/modal/modal.types.ts

@@ -0,0 +1,33 @@
+import type { Snippet } from 'svelte';
+
+type ModalSharedProps = {
+  open: boolean;
+  title: string;
+  dismissOnBackdropClick?: boolean;
+  dismissOnEscape?: boolean;
+  showCloseButton?: boolean;
+  class?: string;
+  children: Snippet;
+  footer?: Snippet;
+  triggerRef?: HTMLElement | null;
+  /**
+   * Fired on user-initiated dismissal. Includes: Escape key (native dialog 'cancel' event),
+   * backdrop click, and the close-X button. EXCLUDES: parent-driven open = false.
+   * Callbacks are not awaited and thrown callbacks do not block close.
+   */
+  ondismiss?: () => void;
+};
+
+type DialogModalProps = ModalSharedProps & {
+  role?: 'dialog';
+  /** When set, applied as aria-describedby on the underlying <dialog>. Pass a short, plain description ID only. */
+  describedById?: string;
+};
+
+type AlertDialogModalProps = ModalSharedProps & {
+  role: 'alertdialog';
+  /** Required for alertdialog so assistive technology receives the urgent condition and required action. */
+  describedById: string;
+};
+
+export type ModalProps = DialogModalProps | AlertDialogModalProps;

package/src/components/modal/modal.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/modal/modal.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;