Ask the agent for a focus-order note when it adds a modal or drawer

The new settings drawer looks fine with a mouse. Keyboard users tab into the page behind it, Escape doesn’t close it, and focus stays on the trigger’s neighbor after it closes. The PR description says “added a drawer.”

I’ve started asking the agent for a short focus-order note whenever it introduces a modal, dialog, drawer, or popover. Not a WCAG essay — a four-line checklist of what should happen to focus.

What the note should contain

Four questions, answered in the PR body:

1. On open — where does focus land? (first field, the dialog itself, a title with tabIndex={-1})
2. While open — is tab trapped inside the surface? What’s the expected order?
3. On close (Escape, dismiss, complete) — does focus return to the trigger?
4. If the trigger goes away — where does focus go instead? (a fallback in the same view)

Example:

Focus order (SettingsDrawer):
- Open: focus moves to the “Display name” input
- Tab cycles: name → timezone → Close → back to name
- Escape and Close restore focus to the “Settings” button
- If the button unmounts (rare), focus goes to the page h1

That’s enough for a reviewer to test in a minute without opening a wiki.

Why agents skip this

They implement the visible UI first. Focus is easy to omit when the example snippet used div + absolute and a click-outside handler. A note in the PR doesn’t automatically fix the code — it makes the missing behavior obvious, and it gives the agent a concrete list to implement if you send the PR back.

What to put in the prompt

If you add a modal, dialog, drawer, or popover, use the
existing Dialog/Drawer primitive (don’t invent a new
overlay). Implement: initial focus, tab cycle inside,
Escape to close, and restore focus to the trigger.
Add a 4-line “Focus order” section to the PR body
describing those four behaviors. Don’t claim it works
if you didn’t wire it.

Point at the primitive your design system already has (Dialog, Modal, Sheet). Reinventing focus traps is how you get two Escape handlers and none that work.

A lightweight review pass

You don’t need a full audit. In the Storybook story or the local page:

1. Keyboard only: open from the trigger, confirm you’re not still on the page behind it
2. Tab a full loop — no hidden offscreen stops, no leap into the footer
3. Escape closes, focus is back on the trigger
4. Compare that to the note; if the note is missing, request it before arguing about typography

If the team already has a dialog primitive with this behavior, the note can be one line: “Uses <Dialog> defaults; trigger is Settings.” That’s still better than silence.

Reject / send back

Reject

• A new overlay with no focus note and no obvious primitive
• div + position: fixed “modals” that leave focus on the page
• A note that says “keyboard works” with no open / tab / close detail
• Close-on-overlay-click without Escape, or Escape that doesn’t restore focus

Accept

• A system Dialog/Drawer, plus the four-line note (or a one-liner that it uses defaults)
• A documented exception (rare) with a fallback focus target
• A follow-up only when the gap is named and not in the user’s critical path — prefer fixing it in the same PR

Tiny habit

When you ask an agent to add a modal or drawer, require the focus-order note in the same breath as the screenshot. If the note is missing, the behavior is probably missing too.