workutils/docs/superpowers/specs/2026-08-01-workutils-unified-ui-design.md

WorkUtils 统一 UI 设计规范

日期：2026-08-01

1. 目标与视觉基准

本轮统一 WorkUtils 桌面端的应用外壳、排版、间距、图标、控件和异步状态，使所有功能插件具备一致的视觉语言和交互节奏。设计参考 macOS 与 Codex 桌面端的克制、清晰和高信息密度，但保留 Windows 原生标题栏及窗口按钮，不复制 macOS 红黄绿窗口控制。

最终视觉基准：

基准图用于确定视觉方向和信息层级，不是要求逐像素复制生成图中的系统装饰。实际实现必须服从 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 自动化的业务结构保持不变。