From 9f82aa5caa3dbd953617b5f9f4af95a54be2d7df Mon Sep 17 00:00:00 2001
From: Arun Chintalapati <m@aruns.net>
Date: Mon, 27 Apr 2026 10:07:43 -0500
Subject: [PATCH 1/3] docs(dialog): update demos to match design patterns and
 improve examples

- Change close buttons from secondary to ghost variant for consistency
- Update "With Actions" demo to show save workflow instead of delete
- Add alertdialog role to confirmation demo and update description to explain disablePointerDismissal behavior
- Wrap primary action buttons in Dialog.Close for proper dismissal
- Add JSDoc note about excluding header close button from alertdialog role
- Add descriptive text to "With Actions" example section
---
 .npmrc                                        |  3 ++
 .../src/components/demos/DialogDemo.tsx       | 40 ++++++++++++-------
 .../src/pages/components/dialog.mdx           |  1 +
 .../kumo/src/components/dialog/dialog.tsx     |  3 ++
 4 files changed, 33 insertions(+), 14 deletions(-)
 create mode 100644 .npmrc

diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000000..01eaeec7dd
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,3 @@
+# Override global ~/.npmrc which redirects @cloudflare to an internal registry.
+# This is a public repo — all dependencies are on public npm.
+@cloudflare:registry=https://registry.npmjs.org/
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;

From 2a0b65061c0ff956ab663f575e7c99a72653c32d Mon Sep 17 00:00:00 2001
From: Arun Chintalapati <m@aruns.net>
Date: Mon, 27 Apr 2026 10:07:43 -0500
Subject: [PATCH 2/3] docs(dialog): add JSDoc note about alertdialog role and
 close button exclusion

---
 .changeset/solid-cars-care.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/solid-cars-care.md

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

From a3651cecc48f4ed2ab6067b68c79a8d6494a7667 Mon Sep 17 00:00:00 2001
From: Arun Chintalapati <m@aruns.net>
Date: Mon, 27 Apr 2026 10:07:43 -0500
Subject: [PATCH 3/3] chore: remove accidentally committed .npmrc

---
 .npmrc | 3 ---
 1 file changed, 3 deletions(-)
 delete mode 100644 .npmrc

diff --git a/.npmrc b/.npmrc
deleted file mode 100644
index 01eaeec7dd..0000000000
--- a/.npmrc
+++ /dev/null
@@ -1,3 +0,0 @@
-# Override global ~/.npmrc which redirects @cloudflare to an internal registry.
-# This is a public repo — all dependencies are on public npm.
-@cloudflare:registry=https://registry.npmjs.org/