Rule

Every overlay surface must own its focus state and hand it back correctly on close.

Why

Losing focus context forces screen reader users to re-navigate the entire page after closing an overlay.

Must

• Move focus inside the overlay immediately on open.
• Target the first focusable element or an explicit focus target.
• Trap focus within the overlay while it is open.
• Return focus to the element that triggered the overlay on close.
• If the trigger no longer exists, move focus to a sensible parent.

Should

• Accept a focusTarget prop on overlay components for custom targeting.
• Expose a programmatic close method that always handles focus restoration.

Anti-patterns

• Closing a drawer and leaving focus on the body element.
• Opening a modal inside another modal without separate focus traps.

Test Cases

• Close a modal via Esc and confirm focus returns to trigger.
• Tab key reaches every interactive element inside the overlay.

Telemetry

• overlay_focus_restored
• overlay_focus_lost_errors