diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 7bf0b38..5fdc215 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -627,6 +627,90 @@ $ranking = UserCurrencyLog::whereDate('created_at', today())
 
 ---
 
+### 7.8 全局弹窗系统 `window.chatDialog` ⭐
+
+> [!IMPORTANT]
+> 聊天室内**禁止使用**浏览器原生的 `alert()` / `confirm()` / `prompt()`。
+> 原因：原生弹窗在 Chrome 中会与 `beforeunload` / `pagehide` 事件产生冲突，导致弹窗闪烁消失。
+> **所有需要提示或确认的场景，必须使用 `window.chatDialog`。**
+
+#### 文件位置
+
+```
+resources/views/chat/partials/global-dialog.blade.php   ← 弹窗 HTML + JS
+resources/views/chat/frame.blade.php                    ← 已 @include，全页面可用
+```
+
+#### API 说明
+
+| 方法                                      | 模式              | 返回值             | 说明             |
+| ----------------------------------------- | ----------------- | ------------------ | ---------------- |
+| `chatDialog.alert(msg, title?, color?)`   | 仅「确定」按钮    | `Promise<void>`    | 替代 `alert()`   |
+| `chatDialog.confirm(msg, title?, color?)` | 「取消」+「确定」 | `Promise<boolean>` | 替代 `confirm()` |
+
+参数说明：
+
+- `msg`：弹窗正文内容（字符串）
+- `title`：标题栏文字，默认 `'提示'` / `'请确认'`
+- `color`：标题栏背景色（CSS 颜色值），默认蓝色 `#336699` / 红色 `#cc4444`
+
+#### 使用示例
+
+```javascript
+// ① alert 模式（提示成功 — 绿色）
+await window.chatDialog.alert("操作成功！", "提示", "#16a34a");
+
+// ② alert 模式（提示失败 — 红色）
+await window.chatDialog.alert("网络异常，请稍后重试", "错误", "#cc4444");
+
+// ③ confirm 模式（执行危险操作前确认）
+const yes = await window.chatDialog.confirm(
+    "确定要撤销该用户的职务吗？撤销后将不再拥有相关权限。",
+    "撤销职务", // 标题默认红色
+);
+if (yes) {
+    // 用户点了「确定」
+}
+
+// ④ confirm 模式 — 自定义颜色
+const leave = await window.chatDialog.confirm(
+    "确定要离开聊天室吗？",
+    "离开聊天室",
+    "#cc4444",
+);
+if (leave) {
+    leaveRoom();
+}
+```
+
+#### 在 Alpine.js 组件内使用
+
+`userCardComponent` 组件已通过代理方法封装：
+
+```javascript
+// 在 Alpine.js 组件方法中，可以直接用 this.$alert / this.$confirm
+await this.$alert("任命成功！", "任命成功 ✨", "#16a34a");
+
+const ok = await this.$confirm("确定撤销职务？", "撤销确认");
+if (ok) {
+    /* ... */
+}
+```
+
+这两个方法内部等价于 `window.chatDialog.alert()` / `window.chatDialog.confirm()`。
+
+#### 颜色速查
+
+| 场景            | 推荐颜色                |
+| --------------- | ----------------------- |
+| 成功 / 正向操作 | `#16a34a`（绿色）       |
+| 错误 / 警告     | `#cc4444`（红色）       |
+| 一般提示        | `#336699`（蓝色，默认） |
+| 撤销 / 中性操作 | `#6b7280`（灰色）       |
+| 管理 / 特权操作 | `#7c3aed`（紫色）       |
+
+---
+
 ## 八、常用命令速查
 
 ```bash