dialogs-modals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

当以下情况出现时，可启用本技能：

Agent 构建模态框或对话框组件
Agent 创建确认对话框
Agent 设计破坏性操作警告
Agent 需要实现焦点捕获功能
Agent 构建提示框或输入弹窗

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

模态框打开时，必须在框内捕获焦点
模态框关闭时，必须将焦点返回至触发元素
必须支持通过 Escape 键关闭模态框
必须包含关闭按钮
绝不能将必须完成的关键流程放在模态框中
绝不能在无退出方式的情况下将用户困在模态框内

Common Agent Mistakes

Agent 常见错误

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

未实现焦点捕获（按 Tab 键可跳出模态框）
关闭模态框后未将焦点返回至触发元素
无关闭按钮或不支持 Escape 键关闭
过度使用模态框（造成困扰）
缺少破坏性操作警告

Examples

示例

✅ Correct

✅ 正确示例

tsx

<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>

tsx

<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

❌ 错误示例

tsx

// 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>

tsx

// 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>