Keyboard interaction
Keyboard contracts for overlays
How Gummy UI reasons about triggers, focus containment, dismissal, restoration, roving navigation, and non-modal surfaces across its Base UI overlay components.
By Gummy UI · Published
Begin at the trigger
An overlay interaction starts before the popup is visible. The trigger needs a clear accessible name, native button behavior, and an explicit relationship with the surface it controls. Opening should follow the primitive’s keyboard contract rather than a click-only event attached to a decorative wrapper.
Gummy UI’s dialog, menu, popover, tooltip, sheet, drawer, and related sources compose Base UI parts so triggers, portals, positioners, viewports, popups, titles, descriptions, and close controls remain identifiable. Component detail pages state the expected keyboard behavior rather than relying on the material treatment to imply it.
Match focus behavior to modality
A modal dialog temporarily owns interaction. Focus moves inside, stays contained while the dialog is active, and returns to the trigger after dismissal. A menu uses a different model: items participate in roving focus and typeahead, while Escape closes the menu and restores the trigger. A tooltip does not become a keyboard trap or a substitute for a visible label.
These differences are why one generic “popup” component would be misleading. Shared positioning and visual layers can be reused, but the primitive still owns modality, focus, selection, and dismissal. Tests should exercise the concrete surface rather than assert that every overlay follows the dialog model.
Preserve names and relationships
Dialog and alert-dialog surfaces need a title and, where used, a description connected to the popup. Menu items need roles and state appropriate to ordinary actions, checkboxes, radio choices, groups, separators, or submenus. Popover content can be non-modal but still needs a named trigger and sensible focus order.
Decorative backdrops, reservoirs, bridges, and glints remain silent. The accessible tree should describe the trigger, surface, content, state, and available actions without narrating the Gel Pop material. That separation also allows reduced motion to remove transitions without changing the interaction contract.
Test the return journey
Opening an overlay is only half of the path. Verification should cover Escape, explicit close controls, outside interaction where appropriate, selection, nested surfaces, and focus restoration. It should also check that closed content is not accidentally exposed and that portal behavior does not break naming relationships.
The existing automated suite covers representative overlay states and selected focus paths in a DOM environment. Full launch evidence still needs real-browser keyboard and screen-reader smoke tests. Keeping that limitation visible is preferable to treating a passing visual specimen as complete accessibility evidence.