Field note 2 — Dialog and Popover: what we actually chose

Original to this site (not upstream content). Grounded in the Dialog guide, the declarative control guide and our own build decisions, 2026-11-12.

The guidance’s first rule — pick the first matching rule, default to a modal <dialog> — is written for product UI. A documentation site like this one mostly needs the other end of the spectrum, and being explicit about that was the useful exercise:

• Search is not a dialog. The site search opens as an overlay, but it doesn’t demand a decision or block reading; treating it as a modal would add focus trapping and dismissal behaviour users don’t expect from a lookup tool. The framework’s built-in search UI keeps it non-modal, and we kept it that way rather than rebuilding it as a <dialog>.
• Nothing on this site interrupts. There is no sign-in, checkout or destructive action here, so no page uses showModal() at all. Where the upstream demos show dialogs, they run inside a sandboxed frame on the demo page — the pattern is demonstrated, not imposed on readers.
• Popover-shaped problems stayed popovers. Hover/focus previews (the pattern in the interest-triggered tooltips guide) are transient and light-dismiss by design; promoting them to dialogs would lose exactly the behaviour that makes them cheap.

The honest summary: for a content site, the Dialog guide’s value is mostly negative knowledge — a clear test for when a modal is wrong. We applied that test to our own interface before applying any pattern from it, which is the order the guide itself recommends.