Describe the issue

The current Dialog documentation appears to treat Dialog and Alert Dialog as interchangeable patterns, especially in examples that include destructive or confirmation actions.

Since Kumo uses Base UI under the hood, there is an important accessibility and semantic distinction that is not currently reflected or explained in the docs.

In Base UI:

Dialog

• Uses role="dialog"
• General-purpose, typically dismissible

AlertDialog

• Uses role="alertdialog"
• Enforces stricter accessibility semantics
• Requires explicit user acknowledgment
• Typically non-dismissable via outside click
• Intended for destructive or irreversible actions

In Kumo’s docs, confirmation flows (e.g. Delete, etc.) are shown using Dialog, and they are rendered as role="dialog", even though their UX intent matches alert/confirmation patterns.

Current behavior

The documentation shows patterns such as:

• “Delete” confirmation dialogs
• Destructive primary actions

All implemented using:

<Dialog.Root>
  ...
</Dialog.Root>

These dialogs:

• Are dismissible
• Use role="dialog"
• Do not convey alert dialog semantics for destructive confirmations

Despite visually matching confirmation dialogs, they are documented as generic dialogs without clarification.

Expected behavior

One or more of the following would help clarify intent:

• A dedicated AlertDialog component for confirmation flows

• Clear documentation explaining that:

  • These examples are confirmation dialogs
  • They are implemented with Dialog due to the absence of an AlertDialog abstraction

• Separation of examples into:

  • Presentational dialogs
  • Confirmation / destructive dialogs

• Guidance on accessibility expectations for destructive actions

Why this matters

Using a generic dialog for destructive actions:

• Encourages incorrect patterns for confirmation flows
• Makes accessibility intent unclear
• Forces consumers to infer or reimplement alert semantics themselves

Given that Kumo uses Base UI under the hood (which provides an AlertDialog), this distinction becomes especially relevant for consumers aiming to follow best accessibility practices.

Environment

• Package: @cloudflare/kumo
• Version: 1.0.0
• Browser: All
• OS: All

References

• Dialog docs: https://kumo-ui.com/components/dialog/
• Base UI AlertDialog: https://base-ui.com/react/components/alert-dialog/