imgui-ui-ux-engineering

Dear ImGui UI/UX 工程设计

目的与边界

使用 Dear ImGui 构建专业工具界面。围绕即时模式模型进行设计：应用数据始终是唯一真实来源，而 UI 代码负责呈现当前模型，并将用户意图分发回模型。Dear ImGui 尤其适用于内容创作工具、编辑器与游戏工具、调试面板、运维界面和实时可视化。当面向消费者的产品需要完整的无障碍支持、从右向左（RTL）文本或复杂文本整形时，应明确评估其适用性。[1] [2]

不要把评审当作单纯的外观翻新。应同时改进功能层级、交互成本、错误恢复、信息密度、技术正确性和视觉一致性。

对请求进行分类

将请求归入一个主要工作流。如果提供的代码中既未提及 Dear ImGui，也没有证据表明正在使用它，就不要假设该框架已被采用；只有在用户明确要求时，才提供框架选择评估。如果缺失的信息不会实质性影响解决方案，请做出合理假设；只有存在关键歧义时才提问。

请求	主要交付内容	从以下事项着手确定
新建工具或编辑器	信息架构、工作区框架、面向生产的 C++	用户角色、最重要的三项任务、目标平台
改进现有 UI	审查、重新设计方案、有针对性的代码修改	截图或代码、层级问题、缺失状态
组件设计	行为约定、状态矩阵、ImGui 实现	数据、操作、空状态/错误状态、键盘行为
主题或视觉识别	设计令牌、配色板、字体排印、主题代码	任务密度、品牌限制、对比度要求
代码审查	按优先级排列的问题和安全修复	ID、栈平衡、状态所有权、输入、裁剪、DPI、性能

必需的工作流

1. 提取上下文。 确定用户、主要任务、数据规模、显示尺寸、输入设备、密度偏好和破坏性操作。
2. 构建层级。 让主要操作保持可见，并靠近对应任务；将上下文操作放在所选对象或检查器附近；将低频设置移入菜单或折叠控件。为每个视图定义已选中、空、加载中、错误、未授权和已完成状态。
3. 选择工作区框架。 适用时，使用命令栏、左侧导航或资源面板、中央工作区、右侧检查器、底部日志/进度区域和状态栏。只有在个性化确实有价值时，才持久化停靠和窗口布局。确认所选 Dear ImGui 分支/版本支持所需的停靠 API。[2]
4. 构建设计系统。 集中管理间距、圆角、边框、字体排印、表面层级和语义颜色。从 templates/imgui_design_system.h.in 开始，再根据产品和密度要求进行调整。
5. 围绕任务构建组件。 优先使用内置控件、表格 API 和标准交互。只有在确实需要独特行为或视觉处理时，才使用自定义绘制列表代码。设计常规、悬停、激活、已选中、聚焦、禁用、加载中和错误状态。
6. 设计交互。 验证键盘导航，以及适用时的游戏手柄导航、焦点、快捷键、取消和撤销。始终将原始输入传递给 Dear ImGui；使用 io.WantCaptureMouse、io.WantCaptureKeyboard 和 io.WantTextInput 来决定底层应用是否也接收这些输入。[2]
7. 执行技术审查。 检查标识符冲突、Push/Pop 和 Begin/End 配对、帧内分配、大型列表裁剪、DPI 处理、对比度及特定版本的 API。
8. 验证任务，而不只是像素。 测试窄面板和宽面板、长文本、无数据、数百条记录、任务失败以及仅用键盘操作的情况。验证对齐、操作反馈和恢复路径。

工作区构成

将以下内容作为灵活的构成体系，而非僵化的像素模板。

区域	用途	实施指南
命令栏	常用全局操作、搜索、工作区切换	控制操作数量；将次要命令移入菜单或命令面板。
导航或资源窗格	层级结构、集合、场景、文件、筛选器	提供搜索、可折叠分组、清晰的选中状态和简洁的计数。
中央工作区	画布、表格、时间线、图表或主编辑器	为此处分配最大的空间和对比度；移除非必要的界面装饰。
检查器	所选对象的属性和上下文操作	按用户的心智模型对字段分组；提供实时预览和安全的重置操作。
辅助面板	日志、性能、作业队列、问题列表	不需要时应可关闭或折叠。
状态栏	连接、选中项、进程、坐标或性能状态	保持简洁、实时且可操作。

密度与层级

根据任务频率和数据规模选择密度，然后通过表面层级、字体排版、留白、颜色和布局体现优先级。切勿只用颜色传达含义。有关详细的密度指南和组件规范，请阅读 references/design-playbook.md。[5]

选择合适的组件

组件	适用场景	避免用于
表格或资源浏览器	可排序、可筛选的多列数据	将数千条记录渲染为卡片
检查器	所选对象的可编辑属性	无关的全局设置
指标卡片	少量关键 KPI 和趋势	屏幕上的每一个数字
命令面板	大量命令和面向专家的键盘工作流	将核心操作隐藏在主界面之外
模态框	确认或简短、专注的决策	长期使用的编辑器或综合表单
Toast 提示	简短的成功反馈和撤销操作	作为关键错误的唯一呈现方式
空状态	首次使用或筛选结果为空	让用户面对没有任何说明的空白面板

需要详细的布局模式、组件规范、状态文案或评审标准时，请阅读 references/design-playbook.md。如果具体的输出范例能提升一致性，请在撰写评审或前后对比方案之前阅读 references/worked-example.md。

Dear ImGui 实施规则

状态、标识与结构

将应用模型作为唯一事实来源。仅在 UI 状态与呈现有关时保存，例如面板是否打开、临时筛选文本或拖动预览。对于由指针提供的显示字段，要么强制执行并记录模型中非空的约束，要么让所有 UI 读取都通过空值安全的显示适配器；切勿依赖隐式的可空字符串约定。

为重复使用的控件保证唯一 ID。使用 ## 添加不可见后缀；在循环和动态集合中，使用 PushID()/PopID() 和稳定的对象键；使用 ### 在可见标签变化时保持 ID 稳定。同一作用域中的重复标签会造成冲突。[2]

每个 Push* 都必须配对相应的 Pop*，每个 Begin* 都必须配对对应的 End*。遵循每个 API 的约定；例如，即使窗口当前已折叠，也不要省略必需的 End()。

布局与大型数据集

仅在万不得已时使用固定像素坐标。使用 BeginTable、子区域、可用宽度、弹性列和间距标记来组合布局。让检查器的标签和输入控件分为两列对齐，然后在支持的最窄面板上进行测试。

对于大型集合，构建经过筛选的稳定 ID 视图，并使用 ImGuiListClipper 渲染可见行。提供可排序的列时，应处理 ImGuiTableSortSpecs；仅设置 Sortable 标志而不实际对模型排序，会导致交互不完整。提供排序方向、当前筛选条件摘要、清晰的选中状态，以及有意义的空结果说明。

主题、排版与 DPI

集中管理尺寸。使用一套精简的比例来推导内边距、间距和圆角。使用 WindowBg、ChildBg、PopupBg 和边框来区分层级，而不是给每个面板随意指定色调。

普通文本的对比度至少应达到 4.5:1，大号文本至少应达到 3:1。[4] 如果默认字体在工具的目标尺寸下难以辨认，请选择合适的字体。为 FontScaleDpi 明确指定唯一的控制方：使用模板由宿主管理的策略，并采用宿主提供的缩放值；或者在停靠分支的 io.ConfigDpiScaleFonts 能随着显示器 DPI 的变化自动更新 FontScaleDpi 时，选择由 Dear ImGui 管理的策略。内容缩放发生变化时，仍需重置样式并调用 ScaleAllSizes() 来缩放尺寸和内边距。依赖较新的 API 前，请确认目标版本和后端功能。[3]

键盘、游戏手柄与无障碍

启用 ImGuiConfigFlags_NavEnableKeyboard，并在需要时启用 ImGuiConfigFlags_NavEnableGamepad。测试 Tab/Shift+Tab 遍历、焦点可见性、Escape 取消、Enter 确认以及关键应用快捷键。仅当明确的导航或程序化选择请求需要时，才移动默认键盘焦点；不要每帧都重新将焦点设到已选中的行上。应明确说明 Dear ImGui 内置无障碍功能和完整国际化方面的局限，而不要把更换主题说成完整解决方案。[1]

让焦点、悬停和选中状态在视觉上彼此区别。对于含义不明确的图标或缩写，可用工具提示补充说明，但不要用工具提示解释完成任务所必需的信息。控件被禁用时，应简要说明原因。

自定义绘制与组件约定

编写自定义绘制列表代码前，先判断是否可以组合内置控件、表格、可选项、树、弹出窗口和子区域来满足需求。对于每个自定义控件：

1. 使用相同的坐标模型定义可见边界和命中区域。
2. 生成唯一 ID，并规定正常、悬停、激活、选中、聚焦、禁用、加载和错误状态下的行为。
3. 以书面形式定义点击、拖动、取消和无数据时的行为。
4. 遵守裁剪规则；对于大型数据，仅生成可见几何图形；尽量减少每帧的持久分配。
5. 使用集中定义的令牌绘制颜色、间距和字体；切勿在组件中嵌入随意指定的视觉常量。
6. 以视觉方式验证窄面板/宽面板、低 DPI/高 DPI 以及每种交互状态。

交付物规范

交付物	必须包含
设计提案	用户／任务列表、屏幕区域、优先级层级、状态矩阵、交互说明、实施顺序
C++ 实现	主题令牌、组件函数、ID 策略、状态归属、空状态／错误状态、版本假设
重新设计	改版前后问题表、拟议结构、可衡量的改进目标、针对性变更
代码审查	Critical / High / Medium / Low 优先级、证据、影响、修复方案和验证步骤

使用 templates/imgui_panel_skeleton.cpp.in 构建面向 dockspace 的工作区外壳，并使用 templates/imgui_design_system.h.in 建立集中式令牌系统。将对版本敏感的代码复制到 vendored 或固定版本的 Dear ImGui 项目之前，请先阅读 references/version-notes.md。审查或生成 C++ 源码时，运行 scripts/check_imgui_cpp.py <source...>，以捕获常见的直接 Begin/End 和 Push/Pop 配对错误；请将其视为范围有限的静态防护，而非编译或运行时测试的替代品。要执行自动化结构、语义、对比度、静态检查和编译回归检查，请运行 python3 scripts/run_quality_suite.py；每次常规运行都会获取临时的官方 v1.92.0 和 master 源码，并针对两者编译模板。附带的语义参考响应必须达到 30/30；传入 --semantic-responses RESPONSES.json，即可使用相同规范对目标模型输出进行门禁检查。要验证产品分支，还需提供 --imgui-dir /path/to/vendored/imgui。仅在明确的离线诊断运行中使用 --skip-official-revisions；该选项不能作为发布门禁。仅在修订或回归测试此技能时使用 evals/quality-suite.md 和 evals/failure-mode-regressions.md；后者测试具体的状态、作用域、焦点和 DPI 问题，而非泛泛的输出质量。

发布质量门禁

• 主要任务是否有明显、可见且近在手边的入口？
• 选中、悬停、聚焦、禁用、错误、加载和空状态是否各有清晰区分？
• 主要操作是否与次要操作和破坏性操作明确区分？
• 快捷键、焦点流、Escape／取消和输入捕获是否正确？
• 表格／列表能否处理大量数据、筛选、排序、选择和空结果？
• 控件 ID 是否唯一，Push/Pop 和 Begin/End 调用是否配对？
• 可空模型值能否安全呈现，且默认焦点是否只在收到明确请求后移动？
• 是否已测试对比度、字体易读性、DPI、窄面板和长内容？
• 是否已考虑裁剪、可避免的内存分配和性能分析？
• scripts/run_quality_suite.py 是否已针对每个受支持的 vendored Dear ImGui 头文件版本通过？
• 在适用情况下，是否明确说明了无障碍和国际化方面的限制？

参考资料

[1] Dear ImGui 官方仓库

[2] Dear ImGui 常见问题：范式、ID、输入捕获、导航和停靠

[3] Dear ImGui：字体、DPI 缩放和图标

[4] W3C WCAG 2.2：理解对比度（最低要求）

[5] Nielsen Norman Group：10 条可用性启发式原则