# Dialog

> A modal surface for a focused task; the page waits behind it.

- **Level**: molecule · **Status**: stable · **Role**: feedback
- **Import**: `import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader } from "@rrios-forge/ui/molecules/dialog";`
- **Source**: `packages/ui/src/molecules/dialog`

Modal panel. Composes `@radix-ui/react-dialog` for the full modal contract: `aria-modal`, focus trap, focus return, escape-to-close, outside-click-to-close, body scroll lock, portal isolation. Title + Description are required for accessibility.

## Use it for

- Confirmation modal / generic modal → `Dialog` + `ConfirmDialogContent` / `Dialog`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` `xl` | `md` | Ergonomic scale, in three families (control, text, container). |

## Stories

- [Playground](/?path=/story/components-molecules-dialog--playground) · frame: `/iframe.html?id=components-molecules-dialog--playground&viewMode=story`
- [Sizes](/?path=/story/components-molecules-dialog--sizes) · frame: `/iframe.html?id=components-molecules-dialog--sizes&viewMode=story`
- [With form](/?path=/story/components-molecules-dialog--with-form) · frame: `/iframe.html?id=components-molecules-dialog--with-form&viewMode=story`
- [Focus flow (interaction test)](/?path=/story/components-molecules-dialog--focus-flow) — interaction test · frame: `/iframe.html?id=components-molecules-dialog--focus-flow&viewMode=story`

## Decisions that name it

- ADR-006 — Geometry and typography signature
- ADR-007 — Material highlight on raised surfaces
- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-015 — Drawer molecule on top of Radix Dialog
- ADR-024 — `LocaleSelector` is a new molecule, not an extension of `Combobox`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).