diff --git a/.changeset/solid-cars-care.md b/.changeset/solid-cars-care.md
new file mode 100644
index 0000000000..7b0b06025f
--- /dev/null
+++ b/.changeset/solid-cars-care.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": patch
+---
+
+Add JSDoc note to Dialog.Root role prop clarifying alertdialog should not include a header close button
diff --git a/packages/kumo-docs-astro/src/components/demos/DialogDemo.tsx b/packages/kumo-docs-astro/src/components/demos/DialogDemo.tsx
index 1ff0c5f05c..36dc189e00 100644
--- a/packages/kumo-docs-astro/src/components/demos/DialogDemo.tsx
+++ b/packages/kumo-docs-astro/src/components/demos/DialogDemo.tsx
@@ -22,7 +22,7 @@ export function DialogBasicDemo() {
             render={(props) => (
               <Button
                 {...props}
-                variant="secondary"
+                variant="ghost"
                 shape="square"
                 icon={<X />}
                 aria-label="Close"
@@ -42,18 +42,18 @@ export function DialogBasicDemo() {
 export function DialogWithActionsDemo() {
   return (
     <Dialog.Root>
-      <Dialog.Trigger render={(p) => <Button {...p}>Delete</Button>} />
+      <Dialog.Trigger render={(p) => <Button {...p}>Save changes</Button>} />
       <Dialog className="p-8">
         <div className="mb-4 flex items-start justify-between gap-4">
           <Dialog.Title className="text-2xl font-semibold">
-            Modal Title
+            Save changes
           </Dialog.Title>
           <Dialog.Close
             aria-label="Close"
             render={(props) => (
               <Button
                 {...props}
-                variant="secondary"
+                variant="ghost"
                 shape="square"
                 icon={<X />}
                 aria-label="Close"
@@ -75,8 +75,8 @@ export function DialogWithActionsDemo() {
           />
           <Dialog.Close
             render={(props) => (
-              <Button variant="destructive" {...props}>
-                Delete
+              <Button variant="primary" {...props}>
+                Save
               </Button>
             )}
           />
@@ -88,7 +88,7 @@ export function DialogWithActionsDemo() {
 
 export function DialogConfirmationDemo() {
   return (
-    <Dialog.Root disablePointerDismissal>
+    <Dialog.Root role="alertdialog" disablePointerDismissal>
       <Dialog.Trigger
         render={(p) => (
           <Button {...p} variant="destructive">
@@ -106,8 +106,8 @@ export function DialogConfirmationDemo() {
           </Dialog.Title>
         </div>
         <Dialog.Description className="text-kumo-subtle">
-          This action cannot be undone. This will permanently delete the project
-          and all associated data.
+          This example is using <code>disablePointerDismissal</code>. Try closing this dialog by clicking outside -
+          it should not close.
         </Dialog.Description>
         <div className="mt-8 flex justify-end gap-2">
           <Dialog.Close
@@ -199,7 +199,7 @@ export function DialogWithSelectDemo() {
             render={(props) => (
               <Button
                 {...props}
-                variant="secondary"
+                variant="ghost"
                 shape="square"
                 icon={<X />}
                 aria-label="Close"
@@ -230,7 +230,13 @@ export function DialogWithSelectDemo() {
               </Button>
             )}
           />
-          <Button variant="primary">Create</Button>
+          <Dialog.Close
+            render={(props) => (
+              <Button variant="primary" {...props}>
+                Create
+              </Button>
+            )}
+          />
         </div>
       </Dialog>
     </Dialog.Root>
@@ -255,7 +261,7 @@ export function DialogWithComboboxDemo() {
             render={(props) => (
               <Button
                 {...props}
-                variant="secondary"
+                variant="ghost"
                 shape="square"
                 icon={<X />}
                 aria-label="Close"
@@ -290,7 +296,13 @@ export function DialogWithComboboxDemo() {
               </Button>
             )}
           />
-          <Button variant="primary">Create</Button>
+          <Dialog.Close
+            render={(props) => (
+              <Button variant="primary" {...props}>
+                Create
+              </Button>
+            )}
+          />
         </div>
       </Dialog>
     </Dialog.Root>
@@ -311,7 +323,7 @@ export function DialogWithDropdownDemo() {
             render={(props) => (
               <Button
                 {...props}
-                variant="secondary"
+                variant="ghost"
                 shape="square"
                 icon={<X />}
                 aria-label="Close"
diff --git a/packages/kumo-docs-astro/src/pages/components/dialog.mdx b/packages/kumo-docs-astro/src/pages/components/dialog.mdx
index cbf6967917..ee83002241 100644
--- a/packages/kumo-docs-astro/src/pages/components/dialog.mdx
+++ b/packages/kumo-docs-astro/src/pages/components/dialog.mdx
@@ -170,6 +170,7 @@ export default function Example() {
 
 ### With Actions
 
+<p>Dialog with a primary action and a cancel button in the footer, alongside a header close button.</p>
 <ComponentExample demo="DialogWithActionsDemo">
   <DialogWithActionsDemo client:load />
 </ComponentExample>
diff --git a/packages/kumo/src/components/dialog/dialog.tsx b/packages/kumo/src/components/dialog/dialog.tsx
index 059c797d2d..304393570a 100644
--- a/packages/kumo/src/components/dialog/dialog.tsx
+++ b/packages/kumo/src/components/dialog/dialog.tsx
@@ -265,6 +265,9 @@ export type DialogRootProps = BaseDialogRootProps & {
    * - Confirmation dialogs requiring explicit user acknowledgment
    * - Actions that cannot be undone
    *
+   * Note: Do not include a header close button (`Dialog.Close`) in `alertdialog` — users must
+   * respond via explicit action buttons (e.g. confirm/cancel) in the footer.
+   *
    * @default "dialog"
    */
   role?: KumoDialogRole;