diff --git a/content/components/confirmation-dialog.mdx b/content/components/confirmation-dialog.mdx
new file mode 100644
index 000000000..6c5b13154
--- /dev/null
+++ b/content/components/confirmation-dialog.mdx
@@ -0,0 +1,207 @@
+---
+title: ConfirmationDialog
+description:
+ ConfirmationDialog is a specialized dialog component used to confirm user actions. It provides a rigid two-button
+ interface with a cancel and confirm action.
+reactId: confirmation-dialog
+figmaId: confirmation-dialog
+tags:
+ - modal
+ - popup
+---
+
+import ComponentLayout from '~/src/layouts/component-layout'
+export default ComponentLayout
+import {AccessibilityLink} from '~/src/components/accessibility-link'
+import {Box} from '@primer/react'
+import {Caption} from '@primer/gatsby-theme-doctocat'
+
+ConfirmationDialog is a special kind of dialog with rigid behavior that's used to confirm user actions. It always has exactly two buttons: one to cancel the action and one to confirm it. The component provides no custom rendering capabilities and focuses on consistency across confirmations.
+
+## Anatomy
+
+
+
Anatomy of a ConfirmationDialog.
+
+### Header region
+
+The **header** region contains the confirmation title and close button. The title should clearly describe the action being confirmed, typically phrased as a question (e.g., "Delete repository?", "Discard changes?").
+
+### Body content
+
+The **body** provides additional context about the action's consequences. This content is passed as children to the ConfirmationDialog component.
+
+### Action buttons
+
+The **action region** contains exactly two buttons: a cancel button (left) and a confirm button (right). The confirm button can be styled as `normal` (default), `primary`, or `danger` depending on the severity of the action.
+
+## Usage
+
+Use ConfirmationDialog for actions that require explicit user confirmation, especially when:
+
+- The action is destructive or irreversible
+- The action has significant consequences
+- You need a standardized confirmation pattern
+
+### When not to use
+
+- For complex forms or multi-step processes (use [Dialog](/components/dialog) instead)
+- When you need custom header or footer content
+- For non-destructive actions that can be easily undone
+
+## API
+
+ConfirmationDialog is built on top of the Dialog component but provides a simplified, constrained API:
+
+### Required props
+
+```tsx
+ {
+ // Handle the result
+ // gesture can be: 'confirm', 'cancel', 'close-button', or 'escape'
+ }}
+>
+ This action cannot be undone.
+
+```
+
+### Optional props
+
+```tsx
+
+ Content describing the consequences of the action.
+
+```
+
+## Examples
+
+### Basic confirmation
+
+```jsx
+function DeleteExample() {
+ const [isOpen, setIsOpen] = useState(false)
+
+ const handleClose = (gesture) => {
+ if (gesture === 'confirm') {
+ // Perform the delete action
+ console.log('Confirmed!')
+ }
+ setIsOpen(false)
+ }
+
+ return (
+ <>
+
+ {isOpen ? (
+
+ This action cannot be undone.
+
+ ) : null}
+
+ )
+}
+```
+
+### Dangerous action
+
+```jsx
+
+ This will permanently delete the repository and all of its contents.
+ This action cannot be undone.
+
+```
+
+### Using the useConfirm hook
+
+For programmatic confirmations, use the `useConfirm` hook:
+
+```jsx
+function ExampleWithHook() {
+ const confirm = useConfirm()
+
+ const handleAction = async () => {
+ const confirmed = await confirm({
+ title: 'Are you sure?',
+ content: 'This action cannot be undone.',
+ confirmButtonType: 'danger'
+ })
+
+ if (confirmed) {
+ // Perform the action
+ }
+ }
+
+ return
+}
+```
+
+## Behavior
+
+### Focus management
+
+- When the confirmation is dangerous (`confirmButtonType="danger"`), focus is placed on the Cancel button
+- When the confirmation is not dangerous, focus is placed on the Confirm button
+- Focus returns to the triggering element when the dialog closes
+
+### Button types
+
+- **normal** (default): Standard button styling
+- **primary**: Emphasized styling for important confirmations
+- **danger**: Red styling for destructive actions
+
+### Closing behavior
+
+The `onClose` callback receives a gesture parameter indicating how the dialog was closed:
+
+- `'confirm'`: User clicked the confirm button
+- `'cancel'`: User clicked the cancel button
+- `'close-button'`: User clicked the X close button
+- `'escape'`: User pressed the Escape key
+
+## Accessibility
+
+
+
+ConfirmationDialog follows dialog accessibility patterns and includes:
+
+- Uses `role="alertdialog"` to indicate urgent content requiring user attention
+- Proper focus management and focus trapping
+- Keyboard support (Tab, Shift+Tab, Escape)
+- Screen reader announcements for the confirmation content
+- Clear button labeling for screen readers
+
+### Screen reader considerations
+
+- The title serves as the accessible name for the dialog
+- Body content provides additional context
+- Button labels should be descriptive and action-oriented
+- The dangerous confirmation focus pattern helps prevent accidental confirmations
+
+## Related components
+
+- [Dialog](/components/dialog): For general modal content and custom layouts
+- [Button](/components/button): For action triggers that may open confirmation dialogs
+- [Banner](/components/banner): For non-modal notifications and warnings