Dialogs & Modals

This skill covers modal and dialog design — when to use them, confirmation patterns, destructive actions, and focus management for accessibility.

Use-When

This skill activates when:

• Agent builds modal or dialog components
• Agent creates confirmation dialogs
• Agent designs destructive action warnings
• Agent needs focus trap implementation
• Agent builds alerts or prompts

Core Rules

• ALWAYS trap focus inside modal when open
• ALWAYS return focus to trigger when modal closes
• ALWAYS allow closing with Escape key
• ALWAYS include a close button
• NEVER use modals for critical flows that must complete
• NEVER trap users in modals without escape

Common Agent Mistakes

• No focus trap (tab escapes modal)
• Focus not returned to trigger on close
• No close button or Escape key support
• Using modals for everything (annoying)
• Missing destructive action warnings

Examples

✅ Correct

<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Delete Item</DialogTitle>
      <DialogDescription>
        Are you sure you want to delete this item? This action cannot be undone.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline" onClick={() => setIsOpen(false)}>
        Cancel
      </Button>
      <Button variant="destructive" onClick={handleDelete}>
        Delete
      </Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

❌ Wrong

// No focus management
<div className={isOpen ? 'block' : 'hidden'}>
  <div>Modal content</div>
  <button onClick={onClose}>Close</button>
</div>

// No way to close
<div className="modal">
  Important content
</div>

References

• WAI-ARIA Dialog Pattern
• Modal UX Guidelines