# Core/Modal - Design

## Properties

### Size

Modals come in three sizes: small, medium, and large. Medium is the default size.
The height of the modal adjusts to the content, up to a maximum height.

### Layered modals

Modals automatically stack such that the most recent modal is interactive while preserving the
backdrop of previous layers.

:::warning

Modals should never be layered. This causes accessibility and usability issues. Open modals should be closed before new ones are opened.

Current instances of layered modals in the product should be refactored to no longer be layered.

:::

## Accessibility

### Keyboard interaction

| Key                    | Function                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `Tab`<br />`Shift-Tab` | Moves focus to the next/previous focusable element within the modal. Focus is trapped within the modal. |
| `Escape`               | Closes the modal.                                                                                       |
| `Enter`<br />`Space`   | Activates the focused element (e.g., buttons in the footer).                                            |

### WAI-ARIA Roles, States, and Properties

* The modal container has `role="dialog"` and `aria-modal="true"`.
* The modal title has a unique ID and the modal container has `aria-labelledby` set to that ID.
* The modal overlay has `role="button"` and acts as a backdrop that can close the modal when clicked (if configured).
* Focus is automatically moved to the modal when it opens and restored to the trigger when it closes.
* The `body` element has `overflow: hidden` applied when the modal is open to prevent background scrolling.