diff --git a/docs/superpowers/specs/2026-08-01-workutils-unified-ui-design.md b/docs/superpowers/specs/2026-08-01-workutils-unified-ui-design.md
new file mode 100644
index 0000000..83bdacb
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-01-workutils-unified-ui-design.md
@@ -0,0 +1,286 @@
+# WorkUtils 统一 UI 设计规范
+
+日期：2026-08-01
+
+## 1. 目标与视觉基准
+
+本轮统一 WorkUtils 桌面端的应用外壳、排版、间距、图标、控件和异步状态，使所有功能插件具备一致的视觉语言和交互节奏。设计参考 macOS 与 Codex 桌面端的克制、清晰和高信息密度，但保留 Windows 原生标题栏及窗口按钮，不复制 macOS 红黄绿窗口控制。
+
+最终视觉基准：
+
+![WorkUtils 统一 UI 视觉基准](assets/2026-08-01-workutils-unified-ui-reference.png)
+
+基准图用于确定视觉方向和信息层级，不是要求逐像素复制生成图中的系统装饰。实际实现必须服从 JavaFX、Windows 平台和现有业务能力。
+
+## 2. 已确认的关键决策
+
+1. 采用基准图中的明亮应用外壳、顶部应用栏和侧栏布局。
+2. 侧栏支持展开与折叠；展开态显示图标和文本，折叠态仅显示图标。
+3. “系统设置”只出现在顶部应用栏右侧，侧栏不再显示，避免重复入口。
+4. 所有导航及功能图标使用同一套 16px 线性图标，禁止继续使用 Emoji 或混合字形。
+5. API 接口文档导出采用基准图中的布局：紧凑模式选择、连续表单、独立进度操作区和可调整日志区。
+6. 字体、字重、行高、字距和间距模拟 Codex/macOS 的阅读节奏，但使用 Windows 可稳定获得的字体。
+7. 保持现有业务流程、导出格式、配置格式和插件路由不变。
+
+## 3. 范围
+
+### 3.1 本轮实施
+
+- 重构 `MainWindow` 的顶部应用栏、侧栏、折叠状态和插件标题展示。
+- 将系统设置入口移至顶部应用栏右侧，并从插件导航数据中排除。
+- 建立统一设计令牌：字体、字号、色彩、间距、圆角、控件高度和图标尺寸。
+- 引入单一 JavaFX 图标库并提供语义化图标注册表，替换应用外壳和插件描述中的 Emoji。
+- 统一按钮、输入框、选择框、标签页、表格、树、日志区、卡片、空状态和焦点状态。
+- 统一按钮 loading、进度、取消、成功、失败和禁用状态。
+- 按统一页面骨架迁移 Git 同步、文本对比、MyBatis SQL 导出、MyBatis 逆向工程、扫描和 API 文档导出。
+- 让 Git 分支评审、系统设置及手机 UI 自动化继承全局主题和应用外壳。
+- 重点重排 API 文档导出的“导出配置”页，使其符合已确认基准。
+
+### 3.2 明确不做
+
+- 不重构 Git 分支评审的业务结构、评审流程或 Diff 引擎。
+- 不拆分手机 UI 自动化窗口，也不重写运行/录制状态机。
+- 不重构系统设置内部的信息架构；本轮只迁移入口并适配统一样式。
+- 不改变导出、扫描、生成、同步等后台任务的业务语义。
+- 不为了模拟 macOS 而创建自绘窗口按钮、无边框窗口或平台专属窗口行为。
+- 不增加深色主题；本规范仅定义统一亮色主题。
+
+## 4. 应用外壳
+
+### 4.1 顶部应用栏
+
+- 高度：48px。
+- 左侧依次为：侧栏折叠按钮、WorkUtils 标识、当前插件标题或面包屑。
+- 右侧依次为：系统设置入口、Windows 原生最小化/最大化/关闭区域之外的应用级操作。
+- “系统设置”使用齿轮图标和文本；可通过鼠标及键盘激活。
+- 插件切换后只更新当前插件标题和内容，不重建整个应用外壳。
+- 顶部栏底部使用 1px 中性色分隔线，不使用阴影或渐变。
+
+### 4.2 侧栏
+
+- 展开宽度：214px；折叠宽度：56px。
+- 折叠/展开状态在应用会话内保持；若现有设置存储可安全复用，可持久化到下次启动，否则不新增配置格式。
+- 展开态显示图标与名称；图标和文本间距 12px。
+- 折叠态仅显示图标，必须提供 Tooltip 和 accessible text。
+- 选中项使用淡蓝背景、左侧 3px 蓝色指示条和蓝色图标/文字。
+- Hover 使用中性浅灰背景；不得使用发光、涟漪或文字阴影。
+- 底部提供“收起/展开”入口；顶部汉堡按钮与底部入口调用同一状态控制器。
+- 侧栏不包含“系统设置”。
+
+### 4.3 插件导航顺序
+
+1. Git 仓库同步
+2. Git 分支评审
+3. 文本对比
+4. MyBatis SQL 导出
+5. MyBatis 逆向工程
+6. 扫描功能
+7. API 接口文档导出
+
+现有插件启用/排序配置仍可影响可见性和顺序，但系统设置不得以普通插件项重新进入侧栏。
+
+## 5. 图标系统
+
+- 采用 Ikonli JavaFX 与 Feather 图标包作为唯一图标来源。若没有完全对应的图标，选择 Feather 包内语义最接近的图标；纯装饰图标可省略，不得混入第二套图标库或 Unicode 字形。
+- 默认图标尺寸 16px；应用标识可使用 20px；空状态插图不在本轮创建。
+- 所有图标使用统一视觉盒、笔画粗细、基线和颜色令牌。
+- 建立 `AppIcon` 语义枚举和 `IconFactory`，业务代码引用 `SETTINGS`、`GIT_SYNC`、`EXPORT` 等语义，不直接引用图标库枚举或 Unicode 字符。
+- 图标只辅助含义，关键操作不能只依赖图标；图标按钮必须有 Tooltip、accessible text 和清晰焦点环。
+
+## 6. 排版规范
+
+### 6.1 字体栈
+
+UI 字体按以下顺序选择第一个可用字体：
+
+1. `Segoe UI Variable Text`
+2. `Segoe UI`
+3. `Microsoft YaHei UI`
+4. JavaFX 系统默认 Sans Serif
+
+中文显示依赖系统字体回退，不打包或伪装 SF Pro/PingFang 字体。等宽内容使用 `JetBrains Mono`（若系统存在），否则回退 `Cascadia Mono`、`Consolas`、JavaFX Monospaced。
+
+### 6.2 字号与行高
+
+| 语义 | 字号 | 字重 | 行高/控件高度 |
+| --- | ---: | --- | --- |
+| 页面标题 | 20px | Semibold | 28px |
+| 区块标题 | 15px | Semibold | 22px |
+| 标签页/导航 | 14px | Medium | 20px |
+| 正文/表单标签 | 14px | Regular | 20px |
+| 辅助说明 | 12.5–13px | Regular | 19px |
+| 表格/树正文 | 13px | Regular | 40px 行高 |
+| 日志/路径 | 12.5–13px | Regular Mono | 19px |
+
+不再允许插件自行传入任意标题字号。`Theme` 提供语义字体方法或 CSS 类，旧 `h1(int)`、`body(int)` 等自由尺寸方法在迁移后逐步废弃。
+
+### 6.3 字距
+
+- 中文正文保持 0 字距，避免人为拉开汉字。
+- 拉丁正文保持 0–0.1px 的自然字距。
+- 页面和区块标题可使用约 -0.2px 的轻微紧缩；JavaFX/CSS 无法稳定实现时保持 0，不通过插入空格模拟。
+- 图标与文字的视觉间距由布局容器控制，不在标签文本中添加空格。
+
+## 7. 色彩、间距与形状
+
+### 7.1 色彩令牌
+
+| 令牌 | 建议值 | 用途 |
+| --- | --- | --- |
+| `bg.app` | `#F7F7F8` | 应用背景 |
+| `bg.surface` | `#FFFFFF` | 表单、表格、日志表面 |
+| `bg.subtle` | `#F2F3F5` | Hover、次级区域 |
+| `text.primary` | `#202123` | 主文本 |
+| `text.secondary` | `#667085` | 辅助文本 |
+| `text.muted` | `#98A2B3` | 禁用/弱提示 |
+| `border.default` | `#E4E7EC` | 1px 分隔与边框 |
+| `accent` | `#1677FF` | 选中、焦点、进度、主按钮 |
+| `accent.hover` | `#0F6BE5` | 主按钮 Hover |
+| `danger` | `#D92D20` | 错误和危险操作 |
+| `success` | `#079455` | 成功状态 |
+
+具体值可在实现时根据 AtlantaFX 实际渲染做小幅对比度校正，但不得重新引入深色侧栏、强阴影或大面积高饱和蓝色。
+
+### 7.2 间距和尺寸
+
+- 以 4px 为最小单位、8px 为主要节奏。
+- 控件内部：8px；同组控件：8–12px；区块间：16px；主要区域间：24px。
+- 主内容边距：上下 16px、左右 24px；窄窗口可降至 16px。
+- 普通控件高度：34–36px；紧凑工具按钮 30–32px。
+- 圆角：普通控件 6px；大面板 8px；不使用胶囊形按钮。
+- 阴影默认关闭。只有真正浮层可使用轻量阴影。
+
+## 8. 统一页面骨架
+
+每个插件内容区按以下顺序组合：
+
+1. 页面标题与可选的一句说明。
+2. 可选标签页或主要上下文工具栏。
+3. 主工作区。
+4. 与任务直接相关的进度和操作区。
+5. 可选的日志、历史或结果面板。
+
+页面不再重复绘制应用级标题栏。内容分组优先使用间距、对齐和分隔线；只有需要独立边界或可折叠/调整大小的区域才使用面板边框，禁止卡片嵌套卡片。
+
+## 9. API 接口文档导出布局
+
+### 9.1 标签页
+
+保留“导出配置 / 导出历史 / 基类配置”。标签页高度、字号、下划线和焦点状态由全局主题控制，不在 `ApiDocWindow` 内硬编码。
+
+### 9.2 导出配置
+
+- 将三张过大的模式卡片改为单行分段选择器。
+- 每段包含统一图标、标题和一行说明；选择状态使用蓝色描边/单选指示，未选状态保持中性。
+- 模式切换只改变与该模式相关的输入区域，保持现有请求构造和校验规则。
+- 完整类名输入使用全宽字段；标签位于字段上方，说明位于字段下方。
+- “启用接口调试（启动本地代理）”保留为显式复选项，默认状态继续服从既有业务约定；在其下方解释影响。
+
+### 9.3 任务状态与操作
+
+- 进度区与操作按钮位于同一视觉行：左侧为状态标题、进度条和说明，右侧为主操作与取消。
+- 空闲时显示“导出文档”；运行时由 `LoadingButtonBinder` 显示 spinner 和“导出中…”。
+- 可取消任务显示“取消”；不具备真实取消能力时不显示伪取消按钮。
+- 进度同时使用进度条、百分比和文本，不只依靠颜色。
+- 任务运行时只禁用会改变本次请求的控件，导航、历史查看和无关操作保持可用。
+
+### 9.4 日志区
+
+- 日志位于主表单下方，使用等宽字体、19px 行高和弱边框。
+- 支持折叠和垂直调整大小；默认高度以 10–14 行为宜。
+- 日志头部显示“执行日志”，底部显示行数或结果摘要。
+- 日志不得显示密码、令牌或带凭据的远程 URL。
+
+## 10. Loading 与异步状态
+
+所有异步操作遵循同一状态模型：`IDLE -> RUNNING -> SUCCEEDED | FAILED | CANCELLED`。
+
+- `IDLE`：按钮显示动词，spinner 不存在。
+- `RUNNING`：主按钮保留宽度，显示 spinner 和进行中文案；禁止重复触发。
+- `SUCCEEDED`：恢复按钮，状态区显示结果和可执行下一步。
+- `FAILED`：恢复按钮，显示可读错误和重试入口；不把异常堆栈直接显示给普通用户。
+- `CANCELLED`：恢复按钮，明确显示“已取消”；已生成的有效结果不得被误删。
+
+`LoadingButtonBinder` 是按钮 loading 的唯一绑定入口。窗口不得再次直接拼装 spinner、替换图标或散落调用 `setDisable`。`OperationStatusPane` 负责进度、状态和可选取消；按钮 loading 与任务进度共享同一只读运行状态，避免不同步。
+
+## 11. 可访问性与键盘
+
+- 所有图标按钮必须有 accessible text 和 Tooltip。
+- 侧栏展开/折叠后保持合理的 Tab 顺序和焦点位置。
+- 焦点环必须清晰可见，不能通过全局 CSS 移除。
+- 文本与背景、禁用状态、选中状态满足可辨识对比度；最终通过实际渲染和对比度工具复核。
+- 任务状态变化同步更新 accessible text；成功、失败和运行状态不只依靠颜色或动画。
+- 动画只用于 120–180ms 的侧栏宽度/透明度过渡和 spinner；若 JavaFX 动画造成布局抖动，则优先稳定布局并取消宽度动画。
+
+## 12. 代码边界与可维护性
+
+建议拆分为以下独立单元：
+
+- `DesignTokens`：语义字体、颜色、间距、尺寸和圆角；不得包含业务状态。
+- `AppIcon` / `IconFactory`：业务语义到图标库的唯一映射。
+- `AppShell`：顶部栏、侧栏、折叠状态和内容插槽。
+- `NavigationModel`：只描述可见插件、顺序、选择和打开动作。
+- `PageHeader` / `SectionHeader`：统一标题结构。
+- 现有 `LoadingButtonBinder` 和 `OperationStatusPane`：继续作为异步展示边界，不引入第二套 loading 组件。
+
+插件窗口只组合公共组件和业务控件，不负责设置全局字体、应用背景、侧栏或系统设置入口。禁止新增大段 `setStyle(...)`；动态状态通过伪类或语义 CSS class 表达。
+
+## 13. 实施优先级
+
+### P0：应用外壳与设计令牌
+
+- 字体栈、色彩、间距、控件尺寸和全局 CSS。
+- 统一图标注册表。
+- 新顶部栏、系统设置入口和可折叠侧栏。
+- 基础控件和焦点/禁用/loading 状态。
+
+### P1：API 文档导出
+
+- 按基准图重排“导出配置”。
+- 复用现有 Tab、请求、代理、历史和异步控制器。
+- 添加可调整日志区及任务状态一致性测试。
+
+### P2：其余核心插件迁移
+
+- MyBatis 逆向工程、MyBatis SQL 导出、扫描、Git 同步、文本对比。
+- 每个插件只迁移页面骨架与样式，不改变业务流程。
+
+### P3：受限适配与收尾
+
+- Git 分支评审、手机 UI 自动化、系统设置只做主题和外壳适配。
+- 清理遗留 Emoji、任意字号和内联样式。
+- 全量视觉回归、键盘与可访问性验收。
+
+## 14. 测试与验收
+
+### 14.1 自动化
+
+- 设计令牌、字体回退和图标语义映射单元测试。
+- 侧栏展开/折叠、选择保持、Tooltip 和 accessible text 组件测试。
+- 系统设置只存在一个应用级入口的结构测试。
+- `LoadingButtonBinder` 在五种状态下的文案、spinner、禁用和恢复测试。
+- API 导出三种模式、代理开关、请求构造、运行/取消/失败恢复和历史刷新测试。
+- 架构约束：插件窗口不得新增 Emoji 导航图标、直接 loading 拼装或应用级系统设置入口。
+
+### 14.2 视觉验收
+
+在相同窗口尺寸和相同业务状态下，将实现截图与视觉基准并排比较，逐项检查：
+
+- 顶部栏与侧栏尺寸、折叠行为和唯一系统设置入口。
+- 字体层级、行高、标签与输入字段对齐。
+- 图标风格、尺寸、基线及图文间距。
+- 内容留白、边框、圆角、颜色和无多余嵌套卡片。
+- API 导出模式选择、进度操作行和日志区。
+- loading 时按钮宽度稳定、spinner 不抖动、无关操作可用。
+
+视觉稿中的 macOS 红黄绿窗口按钮不属于验收目标；Windows 原生标题栏显示正常即为通过。
+
+### 14.3 完成标准
+
+- Maven 全量测试和编译通过。
+- `git diff --check` 通过。
+- 主要插件在展开和折叠侧栏下均无裁切、重叠或跳动。
+- 1024px 与 1440px 宽度下核心流程可用；低于最小支持宽度时允许滚动，不允许控件消失。
+- 系统设置只在右上角出现，侧栏无重复项。
+- 全局导航不再使用 Emoji，业务插件无新增任意字号或重复 loading 代码。
+- Git 分支评审和手机 UI 自动化的业务结构保持不变。
diff --git a/docs/superpowers/specs/assets/2026-08-01-workutils-unified-ui-reference.png b/docs/superpowers/specs/assets/2026-08-01-workutils-unified-ui-reference.png
new file mode 100644
index 0000000..690c27c
Binary files /dev/null and b/docs/superpowers/specs/assets/2026-08-01-workutils-unified-ui-reference.png differ