frontend-component-modal-toast-system

name	frontend-component-modal-toast-system
description	Use when building a confirm modal, alert dialog, or settings overlay with the HTML `<dialog>` element, building a toast notification system with the Popover API plus an `aria-live` region, wiring focus restoration after a modal closes, choosing between `aria-live="polite"` and `aria-live="assertive"` for a toast announcement, managing a queue of stacked toasts with auto-dismiss and pause-on-hover, animating dialog or popover open / close with `@starting-style`, or migrating off a custom focus-trap library to native `showModal()`. Prevents the most common modal and toast regressions in 2026 : modal that does not trap focus because the team rolled their own JS instead of using `<dialog>.showModal()`, modal whose background page keeps scrolling because the team added `body { overflow: hidden }` instead of relying on `showModal()` auto-inert, modal that loses focus to the body after closing because the trigger reference was not captured, toast that interrupts the screen reader mid-sentence because `aria-live="assertive"` was used for a non-urgent success message, second toast that silently replaces the first because the developer used `popover="auto"` (mutually exclusive in top-layer stack) instead of `popover="manual"`, `aria-live` region created AFTER the message was inserted so no announcement fires, and `role="alert"` used for a periodic-status poll where a polite live region is the correct primitive. Covers the modal pattern (`<dialog>` with `showModal()` for auto-inert, native focus trap, Escape-close, top-layer placement, and `::backdrop` styling), the dialog return-value pattern (`close(value)` and `dialog.returnValue`), the `closedby` attribute (`any`, `closerequest`, `none`) for declarative light-dismiss, the toast pattern (popover with `popover="manual"` + a paired `aria-live` region), the urgency-to-live mapping (polite for status and success, assertive plus `role="alert"` for errors and warnings), the toast queue (max-N visible, auto-dismiss timer, pause on hover and focus, restart on leave, light-dismiss button), focus restoration on close (capture trigger before opening, restore in `close` event), the `@starting-style` plus `transition-behavior: allow-discrete` animation pattern for entry / exit, and the rule that `tabindex` is FORBIDDEN on `<dialog>`. Keywords: dialog, HTMLDialogElement, showModal, show, close, returnValue, closedby, aria-modal, aria-labelledby, aria-describedby, autofocus, role dialog, role alertdialog, role status, role alert, aria-live, polite, assertive, atomic, relevant, popover, popovertarget, popovertargetaction, popover manual, popover auto, popover hint, top-layer, backdrop, focus-trap, scroll-lock, focus restoration, toast queue, auto-dismiss, pause on hover, light-dismiss, starting-style, transition-behavior allow-discrete, modal does not trap focus, body scrolls behind modal, toast not announced, focus lost after close, multiple toasts overlap, modal animation snaps, how do I make an accessible modal, toast notification HTML, confirm dialog pattern, accessible alert, scroll lock modal, how to announce to screen reader, how to queue toasts, how to restore focus after modal
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Component : Modal + Toast System

This skill is the operational reference for building accessible modals and toast notifications using native browser primitives only : the <dialog> element with showModal() for modals, and the Popover API plus an aria-live region for toasts. It covers focus restoration, scroll lock, the live-region urgency mapping, toast queue management, and the @starting-style animation pattern. The skill does NOT cover the popover / dialog API mechanics deep-dive (see [[frontend-impl-popover-dialog-anchor]]), the ARIA roles deep-dive (see [[frontend-a11y-aria-patterns]]), or custom focus-trap libraries (use showModal() instead).

Quick Reference

Floor rules

• ALWAYS use <dialog> with dialog.showModal() for modals. NEVER roll a custom focus-trap JS ; showModal() traps focus, inerts the rest of the document, enables Escape-close, and places the dialog on the top layer for free.
• ALWAYS capture the triggering element before opening a modal AND restore focus to it on the close event. The browser does NOT restore focus automatically.
• ALWAYS use aria-live="polite" for status, success, and informational toasts. NEVER use aria-live="assertive" for non-urgent updates ; it interrupts the screen reader mid-sentence.
• ALWAYS use popover="manual" for stacked toasts. NEVER use popover="auto" ; auto popovers are mutually exclusive in the top-layer stack so a second toast silently replaces the first.
• ALWAYS create the aria-live region in the DOM BEFORE inserting the message. NEVER create the region and the message in the same DOM mutation ; the screen reader observes mutations on a pre-existing region.
• ALWAYS pair <dialog> with aria-labelledby (pointing to the title) OR aria-label. NEVER ship a modal without an accessible name.
• ALWAYS use dialog.close(value) and dialog.returnValue for confirm-style dialogs. NEVER hand-roll a Promise wrapper unless you also need to bridge to async / await.
• NEVER set tabindex on a <dialog> element. MDN forbids it ; the dialog manages its own tabindex.

Decision tree 1 : <dialog> showModal versus popover ?