@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/dialog/content.md

@@ -0,0 +1,436 @@
+# Dialog (https://design.candescent.com/docs/components/dialog)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=4331-429), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/overlays-dialog--default)
+
+A compound modal with a backdrop, focus trapping, keyboard dismissal, and animated presentation.
+
+```tsx
+import { Button, Dialog } from '@cdx-ui/components';
+```
+
+> [!NOTE]
+>
+> **Portal host**
+>
+> `ForgeDesignProvider` mounts the shared portal host automatically. If you do not use the
+> provider, mount one `PortalHost` from `@cdx-ui/primitives` near your app root. On web, to keep
+> the dialog inside an embedded surface such as a device preview, wrap that surface in
+> `PortalProvider` and give its `PortalHost` a `container` element inside it; the fixed overlay
+> stays inside only when an ancestor of the container sets a `transform`.
+
+## Basic
+
+The popup mounts in the app-level portal and covers the viewport, while the trigger remains at its original position.
+
+```tsx
+import { useState } from 'react';
+import { Button, Dialog } from '@cdx-ui/components';
+
+export default function DialogBasicDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={open} onOpenChange={setOpen}>
+      <Dialog.Trigger asChild>
+        <Button>
+          <Button.Label>Open dialog</Button.Label>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Popup>
+        <Dialog.Header>
+          <Dialog.Title>Confirm transfer</Dialog.Title>
+          <Dialog.Description>
+            Review the details before submitting this transfer.
+          </Dialog.Description>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Content>
+          <Dialog.Text>$250.00 will be sent from Checking to Savings.</Dialog.Text>
+        </Dialog.Content>
+        <Dialog.Footer>
+          <Button variant="outline" onPress={() => setOpen(false)}>
+            <Button.Label>Cancel</Button.Label>
+          </Button>
+          <Button onPress={() => setOpen(false)}>
+            <Button.Label>Confirm</Button.Label>
+          </Button>
+        </Dialog.Footer>
+      </Dialog.Popup>
+    </Dialog>
+  );
+}
+```
+
+## Title severities
+
+Set `severity` on `Dialog.Title` to add a status icon and semantic color treatment.
+
+```tsx
+import { useState } from 'react';
+import { Button, Dialog, HStack, type DialogTitleSeverity } from '@cdx-ui/components';
+
+interface DialogScenario {
+  severity: DialogTitleSeverity;
+  color: 'action' | 'danger' | 'warning' | 'success';
+  trigger: string;
+  title: string;
+  description: string;
+  body: string;
+  action: string;
+}
+
+const scenarios: DialogScenario[] = [
+  {
+    severity: 'neutral',
+    color: 'action',
+    trigger: 'Review transfer',
+    title: 'Confirm transfer',
+    description: 'From Everyday Checking to High-Yield Savings',
+    body: 'You are moving $500.00 today. Your available checking balance after the transfer will be $1,842.36.',
+    action: 'Transfer $500',
+  },
+  {
+    severity: 'danger',
+    color: 'danger',
+    trigger: 'Report stolen card',
+    title: 'Report card as stolen?',
+    description: 'Debit card ending in 4821 will be permanently blocked.',
+    body: 'Pending transactions will continue to process. A replacement card will arrive at your mailing address in 5–7 business days.',
+    action: 'Report stolen',
+  },
+  {
+    severity: 'warning',
+    color: 'warning',
+    trigger: 'Review low balance',
+    title: 'Balance may fall below $100',
+    description: 'A scheduled payment could leave your checking account low.',
+    body: 'Your $1,250.00 mortgage payment is scheduled for tomorrow. Based on your current balance, approximately $74.18 will remain.',
+    action: 'View account',
+  },
+  {
+    severity: 'success',
+    color: 'success',
+    trigger: 'View deposit status',
+    title: 'Mobile deposit submitted',
+    description: 'Your $725.00 check was accepted for review.',
+    body: 'Up to $225.00 may be available today. We will notify you when the remaining funds are available.',
+    action: 'Done',
+  },
+];
+
+function SeverityDialog({ scenario }: { scenario: DialogScenario }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={open} onOpenChange={setOpen}>
+      <Dialog.Trigger asChild>
+        <Button variant="outline" color={scenario.color}>
+          <Button.Label>{scenario.trigger}</Button.Label>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Popup>
+        <Dialog.Header>
+          <Dialog.Title severity={scenario.severity}>{scenario.title}</Dialog.Title>
+          <Dialog.Description>{scenario.description}</Dialog.Description>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Content>
+          <Dialog.Text>{scenario.body}</Dialog.Text>
+        </Dialog.Content>
+        <Dialog.Footer>
+          <Button color={scenario.color} onPress={() => setOpen(false)}>
+            <Button.Label>{scenario.action}</Button.Label>
+          </Button>
+        </Dialog.Footer>
+      </Dialog.Popup>
+    </Dialog>
+  );
+}
+
+export default function DialogTitleSeveritiesDemo() {
+  return (
+    <HStack space="sm" className="flex-wrap justify-center">
+      {scenarios.map((scenario) => (
+        <SeverityDialog key={scenario.severity} scenario={scenario} />
+      ))}
+    </HStack>
+  );
+}
+```
+
+## Scrollable content
+
+`Dialog.Content` is not scrollable by default. Wrap long content in a `ScrollView` so the header and footer remain visible. On native, set `keyboardShouldPersistTaps="handled"` so a focused field keeps the keyboard open while the body scrolls.
+
+```tsx
+import { useState } from 'react';
+import { Button, Dialog, ScrollView } from '@cdx-ui/components';
+
+const terms = [
+  'Authorization. You authorize us to debit the selected funding account and credit the destination account for the amount shown in the transfer review.',
+  'Account details. You are responsible for confirming the routing number, account number, recipient name, and transfer amount before submitting the transfer.',
+  'Processing times. Transfers submitted after the daily cutoff, on weekends, or on bank holidays may begin processing on the next business day.',
+  'Available balance. Scheduled and recurring transfers are completed only when the funding account has enough available funds on the processing date.',
+  'Fees. Your review screen displays any transfer fee before submission. The receiving financial institution may charge additional fees.',
+  'Cancellation. A pending transfer can be canceled from Transfer Activity until processing begins. Completed transfers cannot be canceled.',
+  'Returns. A transfer may be returned if the destination account is closed, restricted, or entered incorrectly. Any returned funds will be credited back to the funding account.',
+  'Limits. Daily and monthly transfer limits apply across all eligible accounts and may change based on account history and security reviews.',
+  'Notifications. We will send a confirmation when the transfer is submitted and another notification if its status changes.',
+  'Records. Keep the confirmation number for your records and review your account activity to verify that the transfer was completed as expected.',
+];
+
+export default function DialogScrollableContentDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={open} onOpenChange={setOpen}>
+      <Dialog.Trigger asChild>
+        <Button variant="outline">
+          <Button.Label>Review transfer agreement</Button.Label>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Popup>
+        <Dialog.Header>
+          <Dialog.Title>Electronic transfer agreement</Dialog.Title>
+          <Dialog.Description>
+            Review the complete agreement before linking an external account.
+          </Dialog.Description>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Content>
+          <ScrollView
+            className="h-60"
+            contentContainerClassName="gap-3"
+            keyboardShouldPersistTaps="handled"
+          >
+            {terms.map((term, index) => (
+              <Dialog.Text key={term}>
+                {index + 1}. {term}
+              </Dialog.Text>
+            ))}
+          </ScrollView>
+        </Dialog.Content>
+        <Dialog.Footer>
+          <Button variant="outline" onPress={() => setOpen(false)}>
+            <Button.Label>Not now</Button.Label>
+          </Button>
+          <Button onPress={() => setOpen(false)}>
+            <Button.Label>Agree and continue</Button.Label>
+          </Button>
+        </Dialog.Footer>
+      </Dialog.Popup>
+    </Dialog>
+  );
+}
+```
+
+## Required action
+
+Disable backdrop and Escape-key dismissal when the user must explicitly respond. Omit `Dialog.Close` so no close button is shown. Escape dismissal is web only; Android's hardware back button still closes the dialog.
+
+```tsx
+import { useState } from 'react';
+import { Button, Dialog } from '@cdx-ui/components';
+
+export default function DialogNonDismissibleDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={open} onOpenChange={setOpen} closeOnBackdropPress={false} closeOnEscKey={false}>
+      <Dialog.Trigger asChild>
+        <Button variant="outline">
+          <Button.Label>Open required action</Button.Label>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Popup>
+        <Dialog.Header>
+          <Dialog.Title severity="warning">Session expired</Dialog.Title>
+          <Dialog.Description>This dialog requires an explicit response.</Dialog.Description>
+        </Dialog.Header>
+        <Dialog.Content>
+          <Dialog.Text>Sign in again to continue using online banking.</Dialog.Text>
+        </Dialog.Content>
+        <Dialog.Footer>
+          <Button onPress={() => setOpen(false)}>
+            <Button.Label>Sign in</Button.Label>
+          </Button>
+        </Dialog.Footer>
+      </Dialog.Popup>
+    </Dialog>
+  );
+}
+```
+
+## API
+
+### Dialog
+
+Controls open state, dismissal behavior, size, and content padding for the compound component.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children` | `ReactNode` | — | — |
+| `role?` | `'dialog' \| 'alertdialog'` | — | — |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| null` | — | — |
+| `animation?` | `'disable-all'` | — | Pass `'disable-all'` to turn off enter/exit and swipe animations for the popup and overlay. |
+| `isOpen?` | `boolean` | — | Controlled open state. Use `defaultOpen` for the uncontrolled variant. |
+| `onOpenChange?` | `((open: boolean) => void)` | — | — |
+| `defaultOpen?` | `boolean` | — | — |
+| `closeOnBackdropPress?` | `boolean` | — | — |
+| `closeOnEscKey?` | `boolean` | `true` | Close when Escape is pressed. Web only. When `false`, an open dialog still consumes Escape while topmost, so overlays beneath it stay open. Android's hardware back button dismisses independently of this prop. |
+| `fullBleed?` | `boolean` | `false` | Removes horizontal padding from `Dialog.Content`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props), except `children` and `role`.
+
+## Sub-components
+
+### Dialog.Trigger
+
+Opens the dialog when pressed. Use `asChild` to merge trigger behavior onto a `Button` or another pressable element.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### Dialog.Popup
+
+The modal panel, backdrop, and portal composition. The popup inherits `size` from `Dialog` unless overridden.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `forceMount?` | `boolean` | `false` | Keep the popup mounted while the dialog is closed. |
+| `avoidKeyboard?` | `boolean` | — | Whether the content shifts up to clear the on-screen keyboard (native only). No-op on web. Defaults to `true`. |
+| `keyboardVerticalOffset?` | `number` | — | Distance (in px) between the keyboard and the content when keyboard avoidance is active. Forwarded to the underlying keyboard-avoiding layer on native. Defaults to `0`. |
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| null` | — | — |
+| `disableFullWindowOverlay?` | `boolean` | `false` | On iOS, render in a plain `View` instead of `FullWindowOverlay`. Re-enables the element inspector, but the popup no longer layers above native modals. |
+| `isSwipeable?` | `boolean` | `true` | Allow swipe-down to dismiss. Native only; no effect on web. |
+| `zIndex?` | `number` | — | Stacking order for the portal overlay layer (backdrop + popup panel). Defaults to {@link MODAL_OVERLAY_Z_INDEX} (10000). |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Dialog.Header
+
+Container for the title, description, and close action.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Dialog.Title
+
+Heading announced when the dialog opens. Non-neutral severities render a corresponding status icon.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `severity?` | `'neutral' \| 'danger' \| 'warning' \| 'success' \| 'default'` | `'neutral'` | Severity level that controls the status icon and color treatment. |
+| `asChild?` | `boolean` | — | — |
+| `appearance?` | `'danger' \| 'warning' \| 'success' \| 'default'` | — | **Deprecated.** |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props). `appearance` and the `"default"` severity are deprecated; use `severity="neutral"` instead.
+
+### Dialog.Description
+
+Secondary text linked to the popup through `aria-describedby`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Dialog.Content
+
+Body container between the header and footer. Set `fullBleed` on `Dialog` to remove its horizontal padding.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Dialog.Text
+
+Body text styled with the default dialog typography and content color.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Dialog.Footer
+
+Action row rendered below the content.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Dialog.Close
+
+Closes the dialog when pressed. Renders a close icon with the screen-reader label `Close` by default, or merges the behavior onto a custom child when `asChild` is set.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `accessibilityLabel?` | `string` | — | Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+## Hook
+
+### useDialog
+
+Returns the nearest dialog's state and dismissal configuration:
+
+```tsx
+const { open, onOpenChange } = useDialog();
+```
+
+| Return                 | Type                        | Description                                              |
+| ---------------------- | --------------------------- | -------------------------------------------------------- |
+| `open`                 | `boolean`                   | Current open state                                       |
+| `onOpenChange`         | `(open: boolean) => void`   | Updates the open state                                   |
+| `closeOnBackdropPress` | `boolean`                   | Whether backdrop presses dismiss the dialog              |
+| `closeOnEscKey`        | `boolean`                   | Whether Escape dismisses the dialog on web               |
+| `nativeID`             | `string`                    | Generated identifier used by accessibility relationships |
+| `role`                 | `'dialog' \| 'alertdialog'` | Accessibility role applied to the popup                  |
+
+## Accessibility
+
+- The popup receives `aria-modal`, `aria-labelledby`, and `aria-describedby` relationships automatically.
+- Focus moves into the popup, remains trapped while open, and returns to the trigger after close.
+- Escape closes the dialog on web when `closeOnEscKey` is enabled. When it is disabled, Escape is still consumed while the dialog is topmost, so an overlay beneath it stays open.
+- Android's hardware back button closes the dialog.
+
+## Constraints
+
+- A shared `PortalHost` must be mounted once near the app root. `ForgeDesignProvider` includes one.
+- The popup is capped at 85% of viewport height. Put a `ScrollView` inside `Dialog.Content` for long content.
+- Swipe-to-dismiss is native only. Set `isSwipeable={false}` on `Dialog.Popup` to disable it, or pass `animation="disable-all"` on `Dialog` to turn off enter/exit and swipe animations.
+- Native keyboard avoidance is built into `Dialog.Popup`. Do not wrap `Dialog` in another `KeyboardAvoidingView`. On iOS the popup renders inside a `FullWindowOverlay`, a separate native window the surrounding tree cannot reach. Web ignores keyboard avoidance. On Android, confirm the behavior on a device; it varies with edge-to-edge configuration.

package/docs/components/dialog/design.md

@@ -0,0 +1,192 @@
+# Dialog — Design (https://design.candescent.com/docs/components/dialog)
+
+## Usage
+
+**Common alternative names**: Modal, dialog box, popup, lightbox, interstitial
+
+---
+
+## Anatomy
+
+In its most basic form, a dialog is made up of a title, a message, and a dismiss action. Dialogs also commonly contain an affirmative action button and a close button.
+
+**Anatomy\_dialog**
+
+1. **Title**: A short title that describes the content of the dialog.
+2. **Content container**: By default, contains a message that communicates the purpose of the dialog and describes any recommended actions. It also allows for more complex content to be placed inside.
+3. **Close button**: An icon button that closes the dialog and does not execute the affirmative action.
+4. **Affirmative action**: A button used to initiate the action, then close the dialog.
+5. **Dismissive action**: A button that closes the dialog and does not execute the affirmative action.
+
+### Max width
+
+The width of a dialog hugs its content up to a maximum width. The **Size** property is used to set that maximum width.
+
+- **Size: xs** _**(default)**_ – 320px
+- **Size: sm** – 384px
+- **Size: md** – 448px
+- **Size: lg** – 512px
+- **Size: lx** – 576px
+
+---
+
+Usage
+
+### When to use
+
+> [!TIP]
+>
+> **When user action is required to proceed**
+>
+> - ex: To ask the user for confirmation or acknowledgement before proceeding
+> - ex: To ask for user input or selection inside the dialog before proceeding
+
+> [!TIP]
+>
+> **When the user must be blocked from proceeding**
+>
+> - ex: A critical system error is preventing the user from moving to the next step in a flow
+> - ex: A critical system error is preventing the user from submitting a form, saving changes, etc.
+> - ex: A critical system error is preventing the user from submitting a form, saving changes, etc.
+
+> [!TIP]
+>
+> **When the user requests additional information**
+>
+> - ex: User clicks a “View more details” button, and a dialog opens with the additional details the user requested
+
+### When not to use
+
+> [!CAUTION]
+>
+> **Interrupting the user’s task against their best interest**
+>
+> - ex: Promotional content or announcements
+> - ex: A notification that does not require the user’s immediate action
+
+> [!CAUTION]
+>
+> **Contextual feedback that can be handled with an Alert, Snackbar, or Flag**
+>
+> - ex: The Dialog should be used sparingly, because interrupting a user’s current task is a drastic action. Determine if the feedback can be handled with an Alert, Snackbar, or other feedback component before resorting to a Dialog.
+
+> [!CAUTION]
+>
+> **Information not related to the user’s current task**
+>
+> - ex: System-level notifications
+> - ex: Application-level notifications
+
+### Dialog vs Alert Dialog
+
+Both components float above the page with an overlay and center on the viewport. They share layout, max width, and action placement. The difference is **whether the user can leave without choosing**.
+
+**Dialog** — optional **close button**, **backdrop** tap, or **dismissive** action. Use when the user may ignore the message, read optional detail, or complete a short form.
+
+**Alert Dialog** — **no close button**; user **must** select an explicit action. Use when every user must make a clear choice before the app proceeds.
+
+| **Need**                                                | **Use**                              |
+| ------------------------------------------------------- | ------------------------------------ |
+| Optional detail, short form, or “not now” is acceptable | **Dialog**                           |
+| User must choose; ignoring the message is not allowed   | **Alert Dialog**                     |
+| Lightweight feedback; no modal required                 | **Alert**, **Snackbar**, or **Flag** |
+
+### Choosing the right notification type
+
+The Dialog component is just one of several different components that can be used to provide notifications and feedback to users. In addition to the guidance below, see the Notifications pattern for more details on choosing the correct notification type.
+
+### Placement
+
+Dialogs should float above all content on the screen, with a translucent background overlay between the dialog and the content. The dialog should be positioned in the direct center of the screen.
+
+_usage\_layout\_wireframe_
+
+### Action is required
+
+Dialogs force the user to stop their current task by appearing on top of all content, and are persistent until either action is taken or dismissed by the user. This makes dialogs a great tool for when the user is required to make a decision, confirmation, or acknowledgement before proceeding.
+
+Inside the dialog, use the message to communicate the purpose of the dialog and communicate any recommended actions. The dismissive button should decline the primary action and close the dialog. The affirmative button should serve as the confirmation/acknowledgement, then close the dialog.
+
+- **Do:** Use a dialog when the user must make a decision in order to continue.
+- **Do:** Use a dialog when a user must acknowledge a piece of information to continue.
+
+### Preventing user errors
+
+When a user initiates a destructive action, users should be shown a confirmation dialog, as it is possible they pressed the button by mistake.
+
+Inside the dialog, describe the consequences of proceeding with the destructive action. The dismissive button should cancel the action and close the dialog. The affirmative button should be a destructive button that serves as the actual trigger for the destructive action.
+
+- **Do:** Always use a dialog to ask user for confirmation before proceeding with a destructive action.
+- **Don't:** Don’t proceed with a destructive action without asking the user for confirmation.
+
+### Short forms
+
+Dialogs can also be used to present short forms to the user. This type of dialog is very useful for getting quick user input or selection without leaving the current page. It can also be useful when a user has already gone through an entire process, and completing an additional step in a dialog can help them complete an entire other process.
+
+In the example below, the user is completing their purchase. They already provided their name and email address during the checkout process, so simply confirming their details and agreeing to the terms of service can help them complete the registration process as well.
+
+- **Do:** When using a dialog for a form, keep the form short and simple.
+- **Don't:** Do not include multi-step forms in a dialog.
+
+---
+
+## Behavior
+
+### Opening
+
+Dialogs should only open when the user does something on the page, such as clicking a button, following a link, or selecting an option. The user must be aware of the specific context that prompted the dialog.
+
+### Actions
+
+Actions within the dialog should not prompt another dialog to open. Never overlay an overlay.
+
+- **Do:** If the user can take action with just a couple of clicks, a dialog is a good fit.
+- **Don't:** If the user cannot complete the action without an additional dialog, then this action doesn’t make sense in a dialog.
+
+### Closing
+
+For surfaces where the user **must** choose an action and cannot dismiss without committing, use **[Alert Dialog](https://design.candescent.com/docs/components/alert-dialog/content.md)** instead. There are several different ways that a user can close or dismiss a dialog:
+
+1. **Backdrop**: Clicking the backdrop should cancel the action and close the dialog.
+2. **Close button**: Clicking the close button should cancel the action and close the dialog.
+3. **Affirmative action**: Clicking the affirmative action should initiate the action, then close the dialog.
+4. **Dismissive action**: Clicking the dismissive should cancel the action and close the dialog.
+
+_behavior\_closing\_interactions_
+
+### Scrolling
+
+Dialog contents should be fully on screen and not require scrolling. If there is enough content to scroll in the dialog, put it on a separate page instead.
+
+- **Do:** If absolutely necessary, use links within content to share additional information that can’t fit within the dialog. Links should open a new tab within the user’s default device browser.
+- **Don't:** If there is enough content for a scroll bar, a dialog isn’t the right choice. Put long content on a new page, not in a dialog.
+
+## Content
+
+## Number of actions
+
+Dialogs should have two actions: an **affirmative action** or a **dismissive action**. Dialogs are essentially asking the user to decide between these two options.
+
+If additional information is important for the user to understand the need for the action, first determine if a dialog is the right choice. A new page may be a better fit. If additional information is needed only for a small subset of users, a link to additional information that opens in a new tab may be used.
+
+- **Do:** If absolutely necessary, use links within content to share additional information that can’t fit within the dialog. Links should open in a new tab within the user’s default device.
+- **Don't:** Links to additional content should not appear as actions the user can take, as these don’t resolve the reason for interrupting the user’s task.
+
+A notable exception to the two actions rule is when the dialog is asking for a simple acknowledgement, because that action is both affirmative and dismissive. However, be careful that you are not taking away a choice from the user by doing this.
+
+- **Do:** Using a single action is permissible in this case, because the only purpose of the dialog is to notify the user that their payment was sent. Clicking Done serves as both the user’s acknowledgement and desire to dismiss the modal.
+- **Don't:** Don’t use a single action when asking the user to make a choice. In this example, all the user can do is click Agree, which will make them feel forced into that choice. Ensure that users have a way to back out.
+
+## Close button
+
+Dialogs are a conversation between the user and the system. It is required that all dialogs have a way to close, either with a close button in the top right, or a cancel button, that when acted upon by a screen reader or keyboard user will close the dialog.
+
+- **Do:** Best practice is to include a close button AND a dismissive action. However, removing one of those is acceptable, as long as the user has one explicit way to dismiss the dialog.
+- **Don't:** Don’t hide both the close button and the dismissive action. Users must have a way to close the dialog. Don’t assume that users know to click the backdrop. If the user must make a decision before continuing, use an alert dialog instead.
+
+## Complex dialogs
+
+As mentioned in the Short forms section, dialogs can be used to gather quick user input or selection without having to leave the current page. However, multi-step forms or long, scrollable content should not be included in a dialog. Instead, consider using a separate page.
+
+- **Do:** When using a dialog for more complex content, keep it short and simple.
+- **Don't:** Do not include multi-step forms or scrollable content in a dialog. Instead, consider using a separate page.