<!-- Generated by emit-docs.ts — do not edit. -->
# Dialog

Modal dialog on the native <dialog> top layer: focus trap, aria-modal and focus restore come from the platform; title/footer slots, Esc/backdrop/ close-button dismissal via onClose(reason) (D50).

## Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| `open` | `boolean` | — | yes | Controlled open state; syncs to showModal()/close(). |
| `onClose` | `(reason: "esc" \| "backdrop" \| "close-button") => void` | — | yes | Called on every dismissal attempt with its source; the consumer flips `open`. |
| `title` | `ReactNode` | — | no | Heading; renders an <h2> wired to aria-labelledby. Without it, pass aria-label. |
| `footer` | `ReactNode` | — | no | Action row (Buttons — one accent per group, danger for destructive). |
| `width` | `400 \| 560 \| 720` | 560 | no | Panel width in px (400 \| 560 \| 720). |
| `dismissible` | `boolean` | true | no | false = no close button, Esc and backdrop swallowed — footer is the only exit. |
| `ref` | `Ref<HTMLDialogElement>` | — | no | Forwarded ref to the underlying <dialog> element. |
| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |

## Keyboard & assistive tech

| Keys | Behavior |
|---|---|
| Esc | Dismisses via onClose('esc') when dismissible; swallowed otherwise. |
| Tab | Focus is trapped inside by the native <dialog> top layer; restored on close. |

Rendered with showModal(): aria-modal, inert background and focus restore come from the platform. title wires aria-labelledby; without title, pass aria-label. Backdrop click dismisses only when dismissible.

## Theming

Override `--psi-dialog-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).


## Rules

- One accent per visual group; everything else neutral or ghost.
- danger only for actions with real consequences.
- Sizes are px numbers (24|32|40|48), never S/M/L.
- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.