Dialogs are built on Radix Dialog and Radix Alert Dialog with thin wrappers in components/ui/Dialog.tsx and components/ui/AlertDialog.tsx. We expose a small API for sizing/position, a consistent overlay, tokenized colors, and an optional close button. Use Dialog for general content (forms, pickers), and Alert Dialog for confirmations and destructive actions.

1. Primitives: Dialog, DialogTrigger, DialogPortal,DialogOverlay, DialogClose
2. Content & layout: DialogContent (props: size, position, showCloseButton), DialogHeader, DialogFooter, DialogTitle, DialogDescription
3. Props:

• size: sm · default · lg
• position: centered · top
• showCloseButton: true | false (default true)

1. Behavior & styling:

• Overlay: blurred, semi-transparent, animated; outside click and Esc close by default.
• Content: rounded, animated in/out, themed with tokens (light/dark).
• Trigger: use asChild to style a button/link while keeping behavior.

• Uncontrolled: <Dialog> without open/onOpenChange (Radix manages state).
• Controlled: pass open and onOpenChange for complex flows (close on success, block open when invalid, etc.).

1. Form in a dialog:. Wrap the form inside DialogContent. For async submit, use React.useTransition() with TransitionButton for pending state. Close on success with your local setIsOpen(false). Keep footers simple: primary action + secondary cancel (DialogFooter).
2. Top-positioned sheets: Use position="top" for short, frequent interactions (e.g., quick create).
3. Close affordances: Keep the corner close button (showCloseButton) unless the dialog is a single critical choice (then consider Alert Dialog).

DialogTitle and DialogDescription wire ARIA automatically; focus is trapped while open, and Esc/overlay dismiss by default. Icon-only triggers must have an accessible label (aria-label or visually hidden text).

Exports mirror Dialog: AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader/Footer/Title/Description, AlertDialogOverlay/Portal, plus AlertDialogAction and AlertDialogCancel. Use for irreversible actions (delete, reset, leave flow). Actions reuse buttonVariants for consistent styling; drive async work with useTransition + TransitionButton, then close on success.

• General UI (forms, pickers, multi-step content) → Dialog
• Confirm dangerous/critical action → Alert Dialog
• Real link or custom element as trigger → Trigger asChild
• Loading feedback inside actions → TransitionButton with useTransition()

• Size & position via DialogContent size/position.
• Corner close visibility via showCloseButton.
• Header/footer composition via DialogHeader / DialogFooter.
• Keep styling via tokens; use className only for small tweaks - avoid one-off colors.