docs: 重构 Windows UI UX skill 分层
This commit is contained in:
QiuSW
@@ -1,112 +1,137 @@
|
||||
---
|
||||
name: win-ui-ux-design
|
||||
description: 为 WinUI 3、Windows App SDK、XAML、Fluent Design，以及使用 PySide 或 PyQt 面向 Windows 的 Qt for Python 应用设计、评审和实现专业的 Windows 桌面端 UI/UX。当任务涉及 Windows 桌面应用外壳或界面、PySide6、PyQt6、PySide2、PyQt5、Qt Widgets、QML、导航与窗口化、标题栏、NavigationView 或框架等价控件选择、响应式 XAML 或 Qt 布局、主题资源、QPalette 或 QSS、Mica 或 Acrylic、HTML 交互原型、客户评审与设计确认、键盘/鼠标/触控交互、无障碍、设计系统规范、UI 审查，或将已确认的设计转换为 WinUI 3、PySide 或 PyQt 代码时使用。
|
||||
name: windows-ui-ux
|
||||
description: 为 Windows 桌面应用设计、评审、制作 HTML 交互原型并实现专业 UI/UX，覆盖通用桌面交互、Windows/Fluent 平台规范，以及 WinUI 3、Windows App SDK、XAML、PySide、PyQt、Qt Widgets、QML 和 Go Gio 的框架适配。当任务涉及 Windows 应用外壳、导航、标签页、多窗口、多 Tab 数据工作台、表格筛选与行交互、表单验证、导入与前置命令、生成/更新/提交操作、对话框、反馈、长任务、主题颜色、Mica/Acrylic、响应式布局、键盘/鼠标/触控、无障碍、HTML 客户确认原型、现有桌面 UI 优化，或把已确认设计转换为 WinUI、Qt/Python 或 Gio/Go 代码时使用。
|
||||
---
|
||||
|
||||
# Windows 桌面端 UI/UX 设计
|
||||
# Windows 桌面 UI/UX
|
||||
|
||||
将 Windows 视为以键盘和指针为主、可调整窗口大小、信息密度较高，同时可能接收触控和笔输入的桌面环境。优先采用用户熟悉的平台行为，而不是装饰性的新奇效果。
|
||||
使用三层模型指导工作：
|
||||
|
||||
## 遵循核心规则
|
||||
1. **核心体验层**定义与语言和框架无关的任务、状态和交互契约；
|
||||
2. **Windows 平台层**定义 Fluent 视觉、窗口化、输入和无障碍基线；
|
||||
3. **框架适配层**把前两层映射到项目实际 API、生命周期和部署方式。
|
||||
|
||||
- 先优化用户任务流程，再设计单个控件的样式。
|
||||
- 优先使用所选框架的标准控件、系统资源和内置交互行为，再考虑创建自定义 UI。
|
||||
- 将键盘、指针、触控、屏幕阅读器、缩放、主题和高对比度视为同一体验，而不是后期适配项。
|
||||
- 定义每个有意义的状态：默认、悬停、按下、焦点、选中、禁用、加载、空、错误、离线或不可用、成功，以及适用时的撤销。
|
||||
- 使用语义化 Token 和主题资源。不得只用颜色表达含义，也不得假设浅色模式的配色可直接用于深色模式。
|
||||
- 保持适合桌面工作的界面密度。不要放大移动端模式，也不要把常用命令隐藏在仅触控手势中。
|
||||
- 根据项目的框架与绑定版本、目标操作系统、打包模型和依赖项，对每个 API、控件和 Toolkit 建议设置版本门槛。
|
||||
- 区分 WinUI 3（`Microsoft.UI.Xaml`）与 UWP/WinUI 2（`Windows.UI.Xaml`）。未经验证不得跨框架复制 API。
|
||||
- 区分 PySide 与 PyQt，以及 Qt Widgets 与 QML。不要在同一应用中混用绑定，也不要把 WinUI 控件名直接写入 Qt 实现。
|
||||
- 将 HTML 原型视为可交互的设计规格和客户确认媒介，不视为最终桌面实现或原生行为证明。
|
||||
不得把某个框架的控件限制冒充通用 UX 原则，也不得把 HTML 原型当作原生行为、性能或无障碍已经通过验证的证明。
|
||||
|
||||
## 执行工作流
|
||||
## 核心规则
|
||||
|
||||
### 1. 确立约束
|
||||
- 先优化用户任务和恢复路径，再装饰单个控件。
|
||||
- 优先使用目标框架的标准控件、主题资源和内置交互，再考虑自定义组件。
|
||||
- 定义默认、悬停、按下、焦点、当前、选中、勾选、禁用、加载、空、错误、离线、成功和撤销等适用状态。
|
||||
- 键盘、指针、触控、屏幕阅读器、缩放、浅色、深色和高对比度属于同一体验。
|
||||
- 使用语义化 Token 管理颜色、字体、间距、几何、层级、图标和动效；不得只用颜色表达含义。
|
||||
- 保持桌面生产力应用所需的信息密度，不放大移动端模式，也不把常用命令藏在手势或悬停中。
|
||||
- 所有 API 与第三方控件建议都要对应项目的准确版本、目标 Windows、打包模型和依赖。
|
||||
|
||||
在提出实现细节前检查项目。确定：
|
||||
## 工作流
|
||||
|
||||
- 框架及其准确的软件包版本；
|
||||
- 最低 Windows 版本，以及已打包或未打包的部署方式；
|
||||
- 主要任务、目标用户、本地化、数据密度和无障碍需求；
|
||||
- 预期窗口尺寸、多窗口行为，以及调整大小和贴靠场景；
|
||||
- 主要输入方式，以及是否需要针对触控优化；
|
||||
- 品牌约束、浅色/深色行为和现有设计 Token。
|
||||
- 客户确认范围、原型保真度、交付方式、审批人和变更流程。
|
||||
### 1. 检查项目与约束
|
||||
|
||||
如果信息缺失，明确说明保守假设，并让版本敏感的建议保持条件化。
|
||||
先检查项目文件、依赖和入口代码，确定：
|
||||
|
||||
### 2. 选择框架路线
|
||||
- 实际语言、UI 框架、绑定和准确版本；
|
||||
- 最低 Windows 版本、打包与部署方式；
|
||||
- 用户、主要任务、数据规模、本地化和无障碍要求；
|
||||
- 窗口尺寸、贴靠、多显示器、多窗口及输入方式；
|
||||
- 品牌、现有设计 Token、浅色/深色和高对比度行为；
|
||||
- 客户确认范围、原型保真度、审批人和变更流程。
|
||||
|
||||
先根据实际依赖选择且只选择一条实现路线：
|
||||
信息缺失时说明保守假设。版本敏感建议必须保持条件化。
|
||||
|
||||
- **WinUI 3：** 使用 `Microsoft.UI.Xaml`，并读取 [controls-and-patterns.md](references/controls-and-patterns.md) 与 [engineering-validation.md](references/engineering-validation.md)。
|
||||
- **PySide/PyQt：** 确认 PySide6、PyQt6 或遗留 Qt 5 绑定，再确定 Qt Widgets 或 QML；读取 [qt-pyside-pyqt.md](references/qt-pyside-pyqt.md)，不要生成 XAML 或 WinUI API。
|
||||
### 2. 读取平台基线并选择一个适配器
|
||||
|
||||
两条路线都必须读取 Windows 视觉基础与输入/无障碍基线。框架未知时先检查项目文件和导入语句，不要同时给出两套混杂实现。
|
||||
Windows 项目始终读取：
|
||||
|
||||
### 3. 建模体验
|
||||
- [Windows 视觉与布局基础](references/windows-foundations.md)
|
||||
- [Windows 输入与无障碍](references/windows-input-accessibility.md)
|
||||
|
||||
定义主要用户任务、信息层级、窗口图、导航模型和命令界面。保持顶级导航浅而清晰。确定哪些工作应放在主窗口、辅助窗口、内联界面、浮出控件或模态对话框中。
|
||||
根据实际依赖只选择一个实现适配器：
|
||||
|
||||
先描述顺利路径和恢复路径，再制作原型或所选框架的界面代码。在导航、调整大小、刷新和错误发生时保留用户上下文。
|
||||
- WinUI 3 / Windows App SDK / `Microsoft.UI.Xaml`：读取 [WinUI 3 适配指南](references/adapter-winui3.md)。
|
||||
- PySide/PyQt：先确认 Qt 5/6、绑定与 Qt Widgets/QML，再读取 [Qt 适配指南](references/adapter-qt.md)。
|
||||
- Go Gio / `gioui.org`：读取 [Gio 适配指南](references/adapter-gio.md)。
|
||||
|
||||
### 4. 定义视觉系统
|
||||
框架未知时先检查项目清单、导入和构建文件。没有专用适配器时，仍使用核心体验层和 Windows 平台层，并输出“概念 → 目标控件/API → 版本依据 → 回退 → 验证”的适配表；不得臆造 API，也不要混写多套框架代码。
|
||||
|
||||
为字体、间距、几何、颜色、层级、材质、图标和动效建立精简的语义系统。除非品牌需要有意偏离，否则使用 Windows 默认规范。阅读 [windows-foundations.md](references/windows-foundations.md)，了解当前 Fluent 原则、响应式断点、主题、材质和动效指南。
|
||||
### 3. 建模任务、导航与状态
|
||||
|
||||
### 5. 将意图映射到控件和模式
|
||||
定义主要任务、信息层级、窗口图、导航模型、命令作用域和状态所有权。先写顺利路径，再写取消、失败、重试、撤销和恢复路径。
|
||||
|
||||
根据交互语义选择控件，而不是根据外观或任意的项目数量阈值。跨菜单、工具栏、上下文菜单和快捷键复用命令。WinUI 项目读取 [controls-and-patterns.md](references/controls-and-patterns.md)；PySide/PyQt 项目读取 [qt-pyside-pyqt.md](references/qt-pyside-pyqt.md) 中的 Qt 控件映射。
|
||||
涉及顶级导航、层级导航、静态标签、文档标签或多窗口时，读取 [导航、窗口与标签规范](references/core-navigation-tabs.md)。在实现前定义稳定身份、历史、焦点、状态恢复、未保存关闭协议、后台任务和窗口所有权。
|
||||
|
||||
### 6. 规定交互与无障碍
|
||||
### 4. 选择交互模式
|
||||
|
||||
记录焦点顺序、方向键行为、访问键、快捷键、指针提示、上下文菜单、触控目标、拖拽替代方式、无障碍名称、状态播报、对比度和缩放。阅读 [input-accessibility.md](references/input-accessibility.md)，了解必需的交互与无障碍基线。该参考中的 `AutomationProperties` 仅适用于 WinUI；PySide/PyQt 项目必须使用 [qt-pyside-pyqt.md](references/qt-pyside-pyqt.md) 中的 Qt Accessibility 映射。
|
||||
按任务语义选择控件，不按截图或任意项目数量阈值选择。
|
||||
|
||||
### 7. 制作 HTML 原型并取得确认
|
||||
- 数据表格、网格或高密度列表：读取 [数据表格交互规范](references/core-data-table.md)，明确当前项、焦点、选择集、勾选集、筛选范围、行默认操作、右键目标和键盘模型。
|
||||
- 表单、设置、编辑器或输入流程：读取 [表单与输入规范](references/core-form-input.md)，明确提交模式、验证时机、异步竞态、错误恢复和未保存策略。
|
||||
- 对话框、确认、通知、进度或后台任务：读取 [对话框、反馈与任务规范](references/core-dialogs-tasks.md)，按风险与干扰程度选择反馈层级。
|
||||
- 多个标签页均含顶部导入/配置、中部表格、底部生成/更新/提交：读取 [多 Tab 数据工作台规范](references/core-data-workspace.md)，统一页面骨架、命令分区与执行反馈。
|
||||
|
||||
对于新产品、主要页面或显著改版，在正式桌面实现前制作可本地运行的 HTML/CSS/JavaScript 交互原型。它必须复用已定义的 Token、内容、状态矩阵和窗口断点，覆盖主流程、关键异常和空/加载/禁用状态，而不接入生产后端。
|
||||
跨按钮、菜单、上下文菜单和快捷键复用同一命令定义。所有指针加速路径都提供可见或键盘等价路径。
|
||||
|
||||
向客户明确浏览器与 WinUI/Qt 在原生控件、窗口管理、字体渲染、系统材质、DPI、无障碍和性能上的差异。以书面验收清单确认信息架构、布局、视觉、文案、流程和状态；记录未确认项与不在原型验收范围内的原生能力。只有确认后才进入桌面实现。小型局部修改可说明理由后跳过此门禁。
|
||||
### 5. 建立视觉系统
|
||||
|
||||
制作或评审原型时读取 [html-prototype-handoff.md](references/html-prototype-handoff.md)，并在交接时建立 HTML 组件到 WinUI 或 Qt 控件的映射。客户要求改变已确认设计时，先更新原型和验收记录，再修改桌面实现。
|
||||
使用 Windows 平台层定义字体、间距、颜色、层级、材质、图标、动效、窗口宽度和强对比回退，再由选定框架适配器落实。默认呈现应具有一致的 Fluent/Windows 风格和颜色系统，而不是未经设计的框架原始界面；同时保留标准控件行为和目标框架可维护性。
|
||||
|
||||
### 8. 工程实现与验证
|
||||
视觉升级现有项目时，先盘点现有主题、控件封装和用户流程，再统一 Token 与高频组件。不要只改 QSS/XAML/绘制颜色而忽略状态、焦点、布局和错误反馈。
|
||||
|
||||
请求实现时，遵循现有架构，并集中管理 Token、命令和状态。保留虚拟化，避免在 UI 线程上执行同步工作。WinUI 项目读取 [engineering-validation.md](references/engineering-validation.md)；PySide/PyQt 项目读取 [qt-pyside-pyqt.md](references/qt-pyside-pyqt.md) 中的 Qt 工程、线程、主题、部署和测试规范。
|
||||
### 6. 制作 HTML 交互原型并确认
|
||||
|
||||
在真实的紧凑、中等和宽窗口宽度下验证结果，而不是只在全屏显示器分辨率下验证。
|
||||
新产品、主要页面或显著改版在正式桌面实现前，制作可本地运行的 HTML/CSS/JavaScript 交互原型，并读取 [HTML 原型与交接规范](references/core-html-prototype.md)。
|
||||
|
||||
## 产出可用于决策的结果
|
||||
原型应：
|
||||
|
||||
对于新设计，提供：
|
||||
- 复用已定义 Token、真实文案、状态矩阵和窗口断点；
|
||||
- 覆盖主流程及关键加载、空、错误、禁用、确认和完成状态；
|
||||
- 用可重置模拟数据，不连接生产凭据、数据库或不可逆操作；
|
||||
- 对表格、表单、标签、工作台和对话框实现对应核心规范中的关键交互；
|
||||
- 以书面清单确认信息架构、布局、视觉、文案、流程和状态。
|
||||
|
||||
1. 假设和目标场景；
|
||||
2. 信息架构与窗口/导航模型；
|
||||
3. 带响应式行为说明的标注布局；
|
||||
4. 控件和命令映射；
|
||||
5. 语义化视觉 Token；
|
||||
6. 交互与状态矩阵；
|
||||
7. 无障碍要求；
|
||||
8. 实现说明和验收检查。
|
||||
9. 需要客户确认时，提供可运行的 HTML 原型、确认清单和桌面控件映射。
|
||||
向客户说明浏览器与目标桌面框架在原生控件、窗口管理、字体、系统材质、DPI、无障碍和性能上的差异。确认后建立“HTML 组件/状态 → 核心交互契约 → 目标适配器控件/API”的交接表。客户更改已确认设计时，先更新原型与验收记录。
|
||||
|
||||
对于评审，先按严重程度列出发现。每项发现都要指出受影响的界面或控件、用户影响、违反的 Windows 约定和具体修正方案。将正确性与无障碍缺陷同主观的视觉润色建议分开。
|
||||
小型、低风险、局部调整可说明理由后跳过原型门禁。
|
||||
|
||||
对于实现，只修改请求范围，复用项目现有模式，构建或运行相关检查，并报告任何仍未验证的 API 或版本假设。
|
||||
### 7. 实现与验证
|
||||
|
||||
## 拒绝常见失败模式
|
||||
遵循项目既有架构，集中管理 Token、命令和状态。保留虚拟化，不在 UI/事件线程执行阻塞工作，处理取消、重复提交、过期结果和窗口/页面销毁后的回调。
|
||||
|
||||
- 不要把过时的 UWP 或已归档 Toolkit API 当作当前 WinUI 3 指南。
|
||||
- 不要推荐使用 `ComboBox` 进行多选；它不支持多选。
|
||||
- 不要假设当前 WinUI 3 项目中存在已归档的 Windows Community Toolkit `DataGrid`。
|
||||
- 不要把 Emoji 用作结构性界面图标；使用平台字形或一致的矢量图标集。
|
||||
- 不要强制在所有表面使用 Acrylic。用材质表达层级，并提供可读的纯色回退方案。
|
||||
- WinUI 标准控件已经公开准确的无障碍名称时，不要强制设置 `AutomationProperties.Name`；Qt 项目使用对应的 Qt Accessibility API，并且只在缺少语义时显式添加名称。
|
||||
- 不要默认确认每次删除。对频繁且可恢复的操作优先提供撤销；仅对代价高或不可逆的后果使用模态确认。
|
||||
- 不要把单一窗口尺寸、主题、DPI、区域设置或输入方式硬编码为设计基线。
|
||||
- 不要在一个进程中混用 PySide 与 PyQt，也不要混用绑定特有的 `Signal`/`Slot` 与 `pyqtSignal`/`pyqtSlot` API。
|
||||
- 不要从工作线程直接读取或修改 `QWidget`、Qt Quick 场景或其他 GUI 对象；通过队列信号把数据结果送回 GUI 线程。
|
||||
- 不要把 QSS 当作完整 CSS，也不要让全局样式表覆盖系统主题、高对比度、焦点和禁用状态。
|
||||
- 不要把 HTML 原型的 DOM、CSS 或 Web 组件逐字移植为 WinUI/Qt 控件，也不要承诺浏览器原型能证明原生窗口行为、性能或无障碍结果。
|
||||
- 不要为了原型接入生产数据库、真实凭据或不可逆操作；默认使用可重置的模拟数据和本地交互。
|
||||
至少验证：
|
||||
|
||||
- 紧凑、中等、宽窗口，贴靠、最大化与跨显示器；
|
||||
- 100%–200% 显示缩放与增大文本；
|
||||
- 浅色、深色、高对比度及透明效果关闭；
|
||||
- 仅键盘、鼠标及声明支持的触控；
|
||||
- Narrator 与适用的无障碍检查工具；
|
||||
- 空、真实、超大、长文本、失败、权限拒绝和慢任务数据；
|
||||
- 最低支持 Windows 与当前支持目标；
|
||||
- 干净环境中的最终打包产物。
|
||||
|
||||
## 交付物
|
||||
|
||||
新设计或改版至少提供：
|
||||
|
||||
1. 假设、用户和目标场景；
|
||||
2. 信息架构、窗口/导航模型和响应式布局；
|
||||
3. 核心交互与状态矩阵；
|
||||
4. 语义视觉 Token；
|
||||
5. 目标框架控件/API 映射及版本依据；
|
||||
6. 键盘、指针、焦点与无障碍要求；
|
||||
7. 加载、失败、取消、重试、确认、完成与撤销策略；
|
||||
8. 验收与测试清单；
|
||||
9. 需要客户确认时的可运行 HTML 原型、确认记录和桌面交接表。
|
||||
|
||||
评审时先报告阻断、严重和中等问题，再列视觉润色。每项指出位置、触发条件、用户影响、违反的规则和最小稳健修正。实现时只修改请求范围，运行相关构建或检查，并报告尚未验证的版本假设。
|
||||
|
||||
## 禁止的失败模式
|
||||
|
||||
- 不混用 WinUI/UWP 命名空间、PySide/PyQt 绑定或 Qt Widgets/QML 的实现习惯。
|
||||
- 不假设 WinUI 3 自带已归档的 Toolkit `DataGrid`，不把 `ComboBox` 当多选控件。
|
||||
- 不把 Qt QSS 当完整 CSS，不从工作线程触碰 Qt GUI 对象。
|
||||
- 不把 Gio Material 默认主题称为 Fluent，不在每帧重建持久 Widget 状态，也不阻塞窗口事件循环。
|
||||
- 不把 HTML DOM/CSS 逐字移植到桌面代码，不用浏览器原型证明原生性能和无障碍。
|
||||
- 不混淆当前项、焦点、选择和勾选；不让单击、双击、复选框和行内按钮重复触发。
|
||||
- 不把导入、筛选、行操作和工作流完成命令堆在一个区域，也不混淆只读“刷新”与写入“更新”。
|
||||
- 不为所有删除或完成操作统一弹确认框，也不为普通成功统一弹模态对话框。
|
||||
- 不为材质效果破坏标题栏、可读性、高对比度或纯色回退。
|
||||
- 不硬编码单一窗口、主题、DPI、语言或输入方式。
|
||||
|
||||
Reference in New Issue
Block a user