modal-toast-dialog-stinger

# modal-toast-dialog Stinger Procedural arsenal for `modal-toast-dialog-wasp-drone`. Encodes the canonical primitive selection matrix, the six-point accessible-modal contract, the four-tier toast-vs-notification taxonomy, and per-primitive implementation patterns for the 2026 React ecosystem. --- ## When this stinger applies Load when `modal-toast-dialog-wasp-drone` is invoked. Typical triggers: - "Which primitive should I use for this dialog?" - "My focus trap isn't working" - "Should this be a toast or a dialog?" - "How do I set up Sonner in Next.js App Router?" - "The drawer isn't scrolling inside" - "Build me a command palette" - "Audit our overlay accessibility" Do NOT load for: - Design token or animation decisions (ux-ui-svelte-wasp-drone owns those) - General React component architecture (react-wasp-drone) - Overlays that gate auth flows (auth-wasp-drone) - Security audit of overlays protecting sensitive actions (security-wasp-drone) --- ## First action when this stinger is loaded 1. Read `guides/00-primitive-selection-matrix.md`: pick the right primitive first. 2. Read `guides/01-accessible-modal-contract.md`: every overlay must pass the six-point contract. 3. Read the per-primitive guide relevant to the request (02 through 05). 4. Use `templates/overlay-audit-report.md` to structure any output report. --- ## Primitive selection matrix (summary) | Need | Canonical primitive | |---|---| | General content modal | Radix `Dialog` | | Destructive confirmation | Radix `AlertDialog` | | Bottom / side sheet, snap points | `Vaul` Drawer | | Ephemeral feedback (success, error, info) | `Sonner` `toast()` | | Command palette / search menu | `cmdk` `Command` (or `CommandDialog`) | | Non-Radix React projects | Headless UI `Dialog` | See `guides/00-primitive-selection-matrix.md` for the full decision table with edge cases. --- ## The six-point accessible-modal contract Every overlay produced by this stinger must satisfy: 1. `aria-modal="true"` on the dialog container. 2. Correct `role`: `"dialog"` for content overlays, `"alertdialog"` for destructive confirmations. 3. **Focus trap**: Tab/Shift+Tab cycles within the overlay only. Never hand-roll; use the primitive's built-in trap. 4. **Escape key**: closes the dialog (AlertDialog may disable Escape for truly irreversible actions). 5. **Scroll lock**: `overflow: hidden` on `<body>` while the overlay is open. 6. **Focus return**: focus returns to the trigger element when the overlay closes. See `guides/01-accessible-modal-contract.md` for implementation details and WCAG 2.2 additions. --- ## Toast-vs-notification taxonomy (summary) | Scenario | Pattern | Primitive | |---|---|---| | Ephemeral feedback (save, delete, copy) | Toast, auto-dismiss | Sonner `toast()` | | Destructive confirmation | Alert dialog | Radix `AlertDialog` | | Error that requires user attention | Persistent toast | `toast.error()` with `duration: Infinity` | | Side panel / filter tray | Drawer | Vaul | | Ambient activity feed | Notification center | Custom tray (out of scope) | See `guides/02-toast-notification-taxonomy.md` for the full decision tree and anti-patterns. --- ## Critical directives - **Mount overlays in a portal outside the app root.** Overlays inside scroll containers or stacking contexts produce z-index and scroll-lock failures. See `guides/03-stacking-and-layering.md`. - **Never re-implement the focus trap.** All known hand-rolled traps fail on Shadow DOM, iframes, or dynamically rendered content. Use the primitive's built-in implementation. - **Apply the taxonomy before recommending a primitive.** Ephemeral toasts masking destructive confirmations are a critical UX failure. - **Validate focus return on close.** The most common overlay accessibility regression. - **Vaul requires `"use client"`.** In Next.js App Router, all Vaul components must be in a client module. --- ## Folder layout ``` modal-toast-dialog-stinger/ ├── SKILL.md (this file) ├── README.md ├── guides/ │ ├── 00-primitive-selection-matrix.md │ ├── 01-accessible-modal-contract.md │ ├── 02-toast-notification-taxonomy.md │ ├── 03-stacking-and-layering.md │ ├── 04-vaul-drawer-patterns.md │ └── 05-cmdk-command-menu.md ├── examples/ │ ├── radix-alert-dialog.md │ └── sonner-with-undo.md ├── templates/ │ └── overlay-audit-report.md ├── reports/ │ └── README.md └── research/ ├── research-plan.md ├── research-summary.md ├── index.md ├── internal/ │ └── command-brief.md └── external/ ├── radix-dialog.md ├── vaul-drawer.md ├── sonner-toast.md ├── aria-apg-dialog.md ├── cmdk-command.md └── toast-taxonomy.md ``` --- *Forged by stinger-forge from `modal-toast-dialog-wasp-drone-command-brief.md` and `research/`. Part of The Wasp Nest by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*