• Content: one short sentence, label, or keyboard shortcut. Never put a link or button inside a tooltip.
• Delay: 300–400ms on hover; no delay on keyboard focus.
• Position: prefer above the trigger; auto-flip when viewport edge is near.
• ARIA:

  role="tooltip"

  on the element;

  aria-describedby

  on the trigger pointing to the tooltip id.

• Max width: 280–360px. For larger content, use a drawer.
• Position: anchored to the trigger; auto-flip to stay in viewport.
• Dismiss: click outside, Escape key, or explicit close button when the content is long.
• Focus: move focus into the popover when it opens; return focus to the trigger on close.
• ARIA:

  role="dialog"

  (if interactive) or

  role="listbox"

  (if a list);

  aria-haspopup

  on the trigger.

• Separate select dropdowns (the user picks one value that persists) from action menus (the user triggers an action that doesn't persist as a value).
• Width: at least as wide as the trigger; cap at 280px.
• Long lists: add a search input at the top when there are more than 8–10 items.
• Keyboard:

  ↑

  /

  ↓

  to move between items,

  Enter

  to select,

  Escape

  to close.

• Peek height: Show a small portion of the sheet first (a handle + title), let the user drag to expand.
• Full-height: For longer content or forms that need the full viewport.
• Dismiss: swipe down, tap the scrim, or press Escape.
• Do not centre dialogs on mobile — use a bottom sheet instead (centred modals are too small and hard to reach).
• ARIA: treat as

  role="dialog"

  with the same focus management as a modal.

• Right drawer: Detail view, editing form, filter/sort panel. Most common.
• Left drawer: Navigation on mobile (hamburger menu pattern).
• Width: 320–480px on desktop. Full-width on mobile (effectively a bottom sheet or full-screen overlay instead).
• Scrim: a semi-transparent backdrop (

  rgba(0,0,0,0.4)

  ) behind the drawer dims the main content.
• Dismiss: Escape key, explicit close button. Clicking the scrim is optional — avoid it when the drawer contains an unsaved form.
• Do not use a drawer when the task is blocking (e.g. a required decision). Use a modal instead.
• ARIA:

  role="dialog"

  ,

  aria-modal="true"

  ,

  aria-labelledby

  pointing to the drawer title.

• Confirming a destructive or irreversible action
• A required form that must be submitted before continuing
• An error or warning that requires the user's acknowledgement

• Displaying information the user can read at their leisure → use an inline notice or notification
• A task the user might want to do alongside the main content → use a drawer
• A large form with many fields → use a dedicated page or a drawer

1. Move focus to the first interactive element inside the overlay (usually the first field, or the confirm button for confirmations).
2. Trap focus:

   Tab

   and

   Shift+Tab

   cycle within the overlay only; focus cannot escape to the content behind the scrim.

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
  aria-describedby="modal-description"
>
  <h2 id="modal-title">Delete project?</h2>
  <p id="modal-description">
    This will permanently delete "Apollo" and all its data. This cannot be undone.
  </p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

• role="dialog"

  on the container

• aria-modal="true"

  tells screen readers to ignore content behind the overlay

• aria-labelledby

  points to the dialog title's id

• aria-describedby

  points to the description's id (optional but helpful for confirmations)
• The scrim backdrop should have

  aria-hidden="true"

  — screen readers must not read it

Delete "Apollo Project"? This will permanently remove all tasks, files, and history. This cannot be undone. [Cancel] [Delete project]

Are you sure you want to do this? [No] [Yes]

• The primary destructive action button uses

  --color-error

  /

  --color-danger

  , not

  --color-primary

  .
• Label the destructive button explicitly: "Delete project", "Remove member", "Cancel order" — not just "OK" or "Confirm".
• Cancel is always on the left (or secondary position); destructive action on the right.

• Is the correct overlay type chosen for the task (tooltip / popover / menu / bottom sheet / drawer / modal)?
• Is a modal avoided when a drawer or inline pattern would suffice?
• Does the modal/drawer have a visible title, body, and clear action buttons?
• Does overflow content scroll within the body — with the header and footer fixed?
• Is Escape disabled for destructive actions (click-outside too)?
• Does focus move into the overlay on open, and return to the trigger on close?
• Is focus trapped within the overlay while it's open?
• Is

  role="dialog"

  ,

  aria-modal="true"

  ,

  aria-labelledby

  set correctly?
• Does the destructive confirm dialog name the item and describe the consequence?
• Is the destructive button labelled explicitly (not "OK" or "Confirm")?
• Are stacked modals avoided?
• On mobile, are modals replaced with bottom sheets?