modal-and-overlay-patterns

Files (1)

• SKILL.md

SKILL.md (first lines)

# Modal and Overlay Patterns

Overlays appear above the main content layer. They range from lightweight popovers (non-blocking, anchored to a trigger) to full blocking modals (require a user response before the app continues). Choosing the right overlay type for the task prevents unnecessary interruption and keeps the user oriented.

---

## The Overlay Hierarchy

Choose the lightest type that satisfies the task. Heavier overlays carry higher cognitive cost.

| Type | Blocks background | Anchored to trigger | Typical content | Dismiss with |
|---|---|---|---|---|
| **Tooltip** | No | Yes | 1–2 lines of explanatory text | Cursor leave / focus out |
| **Popover** | No | Yes | Short interactive content: a form field, a picker, a small list | Click outside, Escape, explicit close |
| **Dropdown / Menu** | No | Yes | List of actions or options | Click outside, Escape, selection |
| **Bottom sheet** (mobile) | Partial (dimmed) | No | Actions or content on small screens | Swipe down, tap scrim, Escape |
| **Drawer / Side panel** | Partial (dimmed) | No | Secondary editing, detail views, long forms | Escape, explicit close; optionally click scrim |
| **Dialog / Modal** | Yes (full scrim) | No | Blocking task: confirm action, fill required form | Escape (non-destructive only), explicit button |
| **Full-screen overlay** | Yes (complete) | No | Immersive task: media viewer, complex configuration | Explicit close only |

**Decision rule:** If the user can continue using the rest of the app while the overlay is open, use a non-blocking type (drawer, popover). If the app must wait for the user's response, use a modal.

---

## One Shell for the Whole Family

Tooltip, popover, drawer, bottom sheet and dialog are one family, not five components. They share a single shell: the same raised surface, one hairline border, one corner radius, and a shadow that grows with modality. The ones that carry a header and footer share what sits inside: a title that names the object, a hairline under the header, and one footer order used everywhere. Only size, anchoring (arrow or centred) and blocking change between them.

When each overlay is styled on its own, the user meets several dialects of the same message: different radii, button orders and confirm labels. Each one costs a moment of re-learning and makes a destructive confirm easier to misread. One shell is also one code primitive and one design-tool family, so a fix lands everywhere.

**Audit before adding.** List every floating surface in the product and the tokens it uses. Extract the shell into one primitive and build each overlay type on it. The usual find is a confirm popover and a dialog that disagree on footer order, or a dialog header still carrying a heavy rule the rest of the UI has dropped.

---

## Tooltip

A tooltip appears on hover or keyboard focus and disappears when the trigger loses focus. It is purely informational — no interactive elements inside.

- 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.

---

## Popover

A popover is anchored to a trigger but contains interactive content — a colour picker, a date range selector, a small form, a list of filters. Unlike a tooltip, it stays open while the user interacts.

- 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.

---

## Dropdown and Menu

A dropdown lists selectable options or actions anchored to a trigger button. It is the lightest interactive overlay.

- 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.

---

## Bottom Sheet (Mobile)

On small screens, a bottom sheet replaces modals and popovers. It slides up from the bottom edge and feels native to touch devices.

- **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.

---

## Drawer / Side Panel

A drawer slides in from the left or right and partially covers the main content. Use it for secondary editing tasks, detail views, or settings that the user might refer back to while using the main content.

- **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.

---

## Modal / Dialog

A modal blocks the entire UI with a full scrim. Use it only when the app genuinely cannot continue without the user's response.

### When to use a modal

- 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

### When not to use a modal

- 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

### The tab-close case
`beforeunload` shows the browser's own generic dialog and nothing else. No script runs and no custom markup paints between that dialog and the unload. Do not design a "rate before you leave" or "review your changes" flow around it. Gate on actions the app controls (close button, route change, new search) and treat tab close as an escape hatch.

### Anatomy

```
┌──────────────────────────────────┐
│  Title                      [✕]  │  ← Header: title + close button
├──────────────────────────────────┤

From dembrandt/dembrandt-skills, MIT.

More from dembrandt/dembrandt-skills