---
name: overlays
description: Builds dialogs, menus, popovers, tooltips, sheets and toasts on the browser's top layer, with declared dismissal and a page that never moves.
title: overlays
canonical_url: https://skilld.dev/gh/raphaelsalaja/skills/overlays
last_updated: 2026-11-22T01:08:19.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/agents/openai.yaml), [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md).
>
> If the user asked to install this Skill, run `npx skilld install raphaelsalaja/skills/overlays`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/overlays`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/raphaelsalaja/skills/overlays) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/overlays`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/overlays --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/overlays --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Overlays

This skill holds how layers above the page open, sit and close. It covers dialogs, menus, popovers, tooltips, sheets, toasts, banners, scroll lock and dismissal.

## The platform first, then these values

Build blocking overlays on `<dialog>` and the rest on `popover`, unless the project's component library already provides them. Where no token exists, the offsets, counts and durations here are exact. An overlay clipped by an ancestor or a page that shifts as one opens is a finding in any style.

Shadows, rings, scroll fades and focus rings inside an overlay belong to `defaults`, and so do live regions and undo. A form inside a dialog belongs to `forms`, and so does the guard on leaving a changed form. How an overlay enters, exits and drags belongs to `motion`, and backdrop contrast belongs to `color`. Walking overlays from the keyboard belongs to `keyboard`, and a dialog taller than a short screen belongs to `viewports`.

## Overlays live in the top layer

A blocking overlay is a `<dialog>` opened with `showModal()`, or by `command="show-modal"` and `commandfor`. Menus, tooltips and toasts use the `popover` attribute. On the top layer, a modal makes the page inert, traps focus, closes on Escape or the back gesture and returns focus on close. The `open` attribute and `show()` give a non-modal dialog that leaves the page live, so a blocking dialog never uses either.

A portal with `z-index: 9999`, `role="dialog"`, `aria-modal` or a hand-written trap is `overlays-top-layer`, unless the project's component library provides it. See [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md#top-layer).

## Dialogs hold focus

A modal moves focus inside on open, keeps Tab inside and returns focus to its trigger on close. Focus left on the page behind an open dialog is `overlays-trap-and-return-focus`.

Focus starts on the element marked `autofocus`, such as the first field of a form. A dialog whose text runs past its first screen focuses its heading instead, set to `tabindex="-1"`, so the start stays in view. A long dialog that opens scrolled down to its first button is `overlays-initial-focus`.

## Dialogs say what they are and how to leave

A dialog takes its name from its visible heading through `aria-labelledby`. A dialog announced only as "dialog" is `overlays-name-the-dialog`.

Every dialog and sheet has a visible Close or Cancel button in its tab order. Escape and outside clicks are invisible, and a touch screen has no Escape key. A dialog that closes only by Escape or a click on the backdrop is `overlays-visible-close`. The button that stands in for a sheet's drag belongs to `motion`.

## One dialog at a time

Never open a dialog on top of a dialog. Use a menu, a popover or a new page. That is `overlays-no-stacked-dialogs`.

No dialog opens on page load. A startup problem, such as being offline, shows cached content with a quiet inline marker. A modal greeting every visit is `overlays-no-dialog-on-load`.

## Dialog buttons keep one order

A dialog footer puts Cancel on the left as a secondary button and the primary action outermost on the right. `Save` left of `Cancel` is `overlays-button-order`. Keeping one primary button per footer belongs to `color`.

## Destructive buttons are never the default

A destructive button is never the default or autofocused, so focus starts on Cancel and Enter never deletes. The rarest and worst actions, such as deleting a workspace, require typing the object's name. A Delete button with `autofocus` is `overlays-destructive-not-default`.

## Locking scroll never moves the page

A modal locks the page in CSS, with `overscroll-behavior: contain` on `dialog:modal` and `overflow: hidden; overscroll-behavior: contain` on `dialog::backdrop`. Safari ignores `overscroll-behavior` on a box that cannot scroll, so `html:has(dialog:modal)` also takes `overflow: hidden`. The root keeps `scrollbar-gutter: stable`, so hiding its scrollbar moves nothing. A centred layout jumping 15px as a dialog opens is `overlays-stable-gutter`.

Never set `position: fixed` on `body` to lock it, because the page jumps to the top and back. See [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md#scroll-lock).

## Outside clicks never lose work

A click outside closes an overlay only when nothing would be lost. A dialog with unsaved input, or a destructive confirm, closes only from its own buttons and Escape. A form dialog that drops typed text on an outside click is `overlays-safe-outside-press`.

Each dialog declares its dismissal. `closedby="any"` allows an outside click, and a dialog holding changes takes `closedby="closerequest"` with a guard in its `cancel` handler. Its Cancel button takes `command="request-close"`, or calls `requestClose()`, so the same guard runs. Safari lacks `closedby`, so the guard stays in `cancel`. One Escape closes one layer, the topmost, which the top layer does on its own. A `mousedown` or Escape `keydown` listener on the document deciding what closes is `overlays-declare-closedby`. See [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md#dismissal).

## Anchored overlays stay on screen

A menu or popover that does not fit flips to the other side of its trigger. Then it shifts along the edge, then caps its height and scrolls inside. It keeps 8px from the viewport edge. A menu cut off at the bottom of the window is `overlays-flip-then-shift`.

Anchored overlays position with CSS anchor positioning, `position-area` and `position-try-fallbacks: flip-block, flip-inline`. Gate `inset: auto; margin: 0` in `@supports`, so an older browser without anchor positioning still shows the popover centred. Leave `position-visibility` at its default rather than `always`, so a menu hides once its trigger scrolls out of view. A scroll listener recomputing `top` and `left` is `overlays-anchor-in-css`. See [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md#anchor-positioning).

## One popover at a time

Only one popover is open at a time. Clicking another trigger closes the open one and opens the new one in the same click, which `popover="auto"` does on its own. A menu bar that needs two clicks to move between menus is `overlays-popover-switch`.

Submenus go one level deep. A submenu past about five items becomes its own menu. A submenu that opens a third level is `overlays-one-submenu-level`.

A submenu stays open while the pointer moves diagonally toward it across its siblings. Keep a triangle from the pointer to the submenu's near edge, and drop it after 300ms or once the pointer leaves it. A submenu that closes as the pointer cuts across the next item is `overlays-submenu-safe-path`.

## Menus hold commands, navigation holds links

`role="menu"` holds commands, with `menuitem` children and arrow keys between them. A dropdown of site links is a disclosure instead: a button with `aria-expanded` and a plain list of `<a href>`. A navigation dropdown built as `role="menu"` around links is `overlays-menu-for-commands`.

## Tooltips hold a label

A tooltip holds a short label and nothing to click. Anything with a link or a button is a popover, opened by a click. A tooltip holding a link is `overlays-tooltip-is-a-label`.

A tooltip is `popover="hint"` with `role="tooltip"`, tied to its trigger by `aria-describedby`, so opening it leaves an open menu alone. A tooltip that only repeats an icon button's `aria-label` skips `aria-describedby`, so the name is not read twice. Safari treats `hint` as `manual`, so the script closes it on blur, leave and Escape. A hover tooltip on `popover="auto"` that closes the open menu is `overlays-tooltip-hint`. See [recipes.md](https://skilld.dev/api/skills-raw/raphaelsalaja/skills/overlays/recipes.md#tooltip).

A tooltip opens on keyboard focus as well as hover, and never closes on a timer. A tooltip that only a pointer can open is `overlays-tooltip-on-focus`.

A tooltip never holds the only copy of something the user needs, because a touch screen has no hover. A plan limit, a price or a warning also shows in the page. A storage limit shown only in a hover tooltip is `overlays-tooltip-not-only-copy`.

A disabled button carries no tooltip, because it takes no focus and keyboard users never reach it. Put the reason beside it as text, or keep it focusable with `aria-disabled="true"` and ignore its clicks. A tooltip explaining a `disabled` button is `overlays-no-tooltip-on-disabled`.

Content shown on hover stays open while the pointer crosses onto it, and closes with Escape. A preview card that vanishes in the gap to its trigger is `overlays-hover-content-stays`.

## Phones get sheets

Below 600px a dialog holding content or a form opens as a bottom sheet. Alerts stay centred at every width. A centred form dialog at 375 is `overlays-sheet-on-phones`.

## Only blocking overlays dim the page

A dialog or sheet dims the page with black at 25–50%. Menus, popovers and tooltips dim nothing. A dimmed page behind a dropdown is `overlays-backdrop-only-modal`.

## One banner at a time

A page shows one banner at a time, in normal flow below the main navigation. It never sticks or stacks, and the next one waits until it closes. Two banners stacked above the header, or one pinned with `position: sticky`, is `overlays-one-banner`.

## Toasts queue

At most three toasts show at once, and the rest queue. A routine toast stays 4–6 seconds and pauses while hovered, focused or while `document.visibilityState` is `"hidden"`. Six toasts stacked at once is `overlays-toast-budget`. Toasts sit 24px from the viewport edge, and 16px below 600px wide.

A toast carrying an action, such as Undo or Retry, or a critical message never closes on a timer. It stays until dismissed or used, with one action of two words or fewer and at most three lines. The action is also reachable outside the toast, such as Restore in the trash. An Undo toast gone after 5 seconds is `overlays-action-toast-stays`.

A repeat toast with a stable id updates the one on screen. Three identical "Saved" toasts stacked is `overlays-toast-in-place`. A loading toast that must end in success or failure belongs to `states`.

## The pair

Every check is a pair. The broken line sits beside the line that replaces it.

| Rule | Broken | Replacement |
| --- | --- | --- |
| `overlays-top-layer` | `createPortal(<Menu />, document.body)` with `z-index: 9999` | `<ul popover>` opened by `popovertarget` |
| `overlays-trap-and-return-focus` | Tab reaching the page behind a dialog | Focus kept inside, then returned to the trigger |
| `overlays-initial-focus` | A terms dialog opening scrolled to its `Accept` button | `<h2 tabindex="-1" autofocus>` at the top of the dialog |
| `overlays-name-the-dialog` | `<dialog>` with a heading and no name, read as "dialog" | `<dialog aria-labelledby="rename-title">` pointing at its `<h2 id="rename-title">` |
| `overlays-visible-close` | A dialog that closes only on Escape or a backdrop click | A visible `Close` button in its header, or `Cancel` in its footer |
| `overlays-no-stacked-dialogs` | A confirm dialog opened from a settings dialog | A menu or popover inside the dialog |
| `overlays-no-dialog-on-load` | An offline dialog on startup | Cached content with an inline `Offline` marker |
| `overlays-button-order` | `Save` on the left, `Cancel` on the right | `Cancel` secondary on the left, `Save` primary on the far right |
| `overlays-destructive-not-default` | `<button autofocus>Delete</button>` in a confirm | Focus on `Cancel`, and typing the name for the worst cases |
| `overlays-stable-gutter` | `overflow: hidden` on `body` shifting the page 15px, or `position: fixed` jumping it to the top | `overscroll-behavior: contain` on `dialog:modal` and its backdrop, `html:has(dialog:modal) { overflow: hidden }` and `html { scrollbar-gutter: stable }` |
| `overlays-safe-outside-press` | A form dialog that closes on an outside click and drops the text | Outside clicks ignored while the form has changes |
| `overlays-declare-closedby` | `document.addEventListener("mousedown", closeIfOutside)` | `<dialog closedby="any">`, or `closedby="closerequest"` with a `cancel` guard and `command="request-close"` on Cancel |
| `overlays-flip-then-shift` | A menu cut off at the bottom of the window | Flipped above its trigger, then shifted, then capped and scrolling |
| `overlays-anchor-in-css` | A `scroll` listener setting `style.top` and `style.left` | `position-area` with `position-try-fallbacks: flip-block, flip-inline` |
| `overlays-popover-switch` | Two clicks to move from one open menu to the next | `popover="auto"`, the next menu opening in the same click |
| `overlays-one-submenu-level` | A submenu opening a third level | One submenu level, a long one split into its own menu |
| `overlays-submenu-safe-path` | `onPointerEnter={() => setOpen(item.id)}` on every item, closing the submenu mid-diagonal | A pointer triangle toward the open submenu, ignored entries inside it, dropped after 300ms |
| `overlays-menu-for-commands` | `<ul role="menu">` holding `<a role="menuitem" href="/pricing">` in the site header | `<button aria-expanded="false">Products</button>` and a `<ul>` of `<a href>` |
| `overlays-tooltip-is-a-label` | A tooltip holding a `Learn More` link | A popover opened by a click |
| `overlays-tooltip-hint` | `<div popover="auto" role="tooltip">` closing the open menu on hover | `<div popover="hint" role="tooltip" id="tip">` with `aria-describedby="tip"` on the trigger |
| `overlays-tooltip-on-focus` | A tooltip on `mouseenter` only, gone after 3 seconds | Open on `focus` and hover, closed on blur, leave or Escape |
| `overlays-tooltip-not-only-copy` | "10 GB limit" only in a tooltip on the storage meter | "4.2 of 10 GB" printed beside the meter |
| `overlays-no-tooltip-on-disabled` | A tooltip on a `disabled` Publish button | "Add a title to publish" beside the button, or `aria-disabled="true"` |
| `overlays-hover-content-stays` | A preview card that closes in the gap to its trigger | The card open while the pointer crosses onto it |
| `overlays-sheet-on-phones` | A centred form dialog at 375 | A bottom sheet below 600px |
| `overlays-backdrop-only-modal` | A dimmed page behind a dropdown | No backdrop on menus and popovers |
| `overlays-one-banner` | A trial banner and an outage banner stacked in a sticky header | One banner in flow below the navigation, the next queued |
| `overlays-toast-budget` | Six toasts stacked at once | Three visible, the rest queued, timers paused while the tab is hidden |
| `overlays-action-toast-stays` | An `Undo` toast gone after 5 seconds | The toast held until dismissed or used, with `Restore` in the trash as well |
| `overlays-toast-in-place` | Three identical "Saved" toasts stacked | `toast("Saved", { id: "save" })` updating the one on screen |

## Reporting

**Severity.** `HIGH` breaks use or access. That is a stacked dialog, focus that escapes a dialog or an overlay cut off by the window or an ancestor. It is also an outside click that drops typed work, a destructive button that Enter can trigger, a tooltip holding a link or one only a pointer can open. It is also a tooltip on a disabled button, or an action toast that closes on a timer. It is also a dialog with no visible way to close it, or something the user needs held only in a tooltip.

`MEDIUM` is a portal at `z-index: 9999`, a page that shifts or scrolls behind a modal, hover content that vanishes or a centred form dialog on a phone. It is also a dialog on page load, dismissal written by hand, a backdrop behind a menu or two clicks between menus. It is also more than three toasts, or repeat toasts that stack. It is also Cancel and the primary action out of order, or banners that stack or stick. It is also an unnamed dialog, a long dialog that opens past its start or links inside `role="menu"`. It is also a submenu that closes on the way to it, or a tooltip that closes the open menu.

`LOW` is an overlay positioned by a scroll listener or a submenu two levels deep.

**Format.** One finding per root cause:

```
file:line - [rule-id] what is wrong
```

Then a `Rule | Count | Severity` summary. `Block` when any `HIGH` remains, `Approve` otherwise. Never `Approve` a file you did not read. Open each overlay from a pointer and from the keyboard when a check depends on behaviour, and mark every check you could not run as `Not verified`.
