# Modality

Choose the lightest layer for a task, and keep layers that open over one another predictable.

* Kind: pattern
* Page: https://design.werklist.com/patterns/modality
* Version: 2.1.2

## When to use it

* Choosing between a tooltip, a menu, a popover, a side sheet and a dialog
* Placing and stacking any layer that opens over the page

## When not to use it

* A layer for an action that can be undone: act and offer Undo
* Two modal layers at once, except a question about the one beneath
* Two anchored layers at once, except a submenu, the list of a field or a tooltip inside a popover or dialog

## Rules

* Pick the lightest layer: a tooltip for a name or a shortcut, a menu for commands, a popover for a few controls on one item, a side sheet for details read against the page, a dialog for an answer or a short task that comes first.
* A layer is placed against the window, so no scrolling list or card cuts it off. It shows once it is in place.
* An anchored layer opens 8 px from its trigger and keeps 8 px from the window edges.
* It opens upward when less than 280 px remains below and there is more room above.
* It is at most 70 percent of the window height and scrolls inside itself when its content is taller. A list inside it is at least 176 px high.
* Its start edge lines up with the trigger and moves to the end edge at the window margin. A tooltip centers on its trigger.
* When the page scrolls, an anchored layer follows its trigger and closes once the trigger has left the view.
* Layer order from the page up: sticky 20, header 40, dialog and sheet 60, toast 70, then tooltip, menu and popover above the toast.
* Escape closes the front layer only, so a menu in a dialog takes two presses.
* One anchored layer at a time, and one modal layer at a time. A question about the modal layer beneath, such as Discard the changes?, is the only modal that stacks.
* When a popover needs a popover of its own, its content moves into a side sheet.
* Focus moves into a layer when it opens and returns to the opener when it closes. If the opener is gone, focus goes to the next row, the previous row, then the list.
* Tab out of a menu or a popover closes it. Behind a dialog or a sheet the page takes no input and does not scroll.
* Anchored layers take the raised fill and shadow, with a 0.5 px rim in dark. On touch screens their fill is opaque (--surface-1). Tooltips take --elevation-2.
* Anchored layers open from opacity 0, 4 px toward the trigger and at scale 0.98, in 150 ms, and close the same way. With reduced motion only the opacity changes.
* Inside a layer, loading shows the frame and a skeleton. Empty says what is missing and offers the next step. An error shows a message at the top of the body and keeps the entries. Success closes the layer, returns focus and confirms with a toast when the result is out of view.
* Layers do not print.

## Tokens

* --layer-sticky
* --layer-header
* --layer-dialog
* --layer-toast
* --layer-popover
* --overlay
* --glass-fill-raised
* --glass-ring-raised
* --elevation-2
* --elevation-3
* --surface-1
* --space-2
* --duration-fast
* --ease-soft
* --ease-standard