docs: 重构 Windows UI UX skill 分层

SKILL.md

@@ -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、语言或输入方式。

agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Windows UI/UX 设计"
   short_description: "设计、原型确认并实现 Windows 桌面端体验"
-  default_prompt: "使用 $win-ui-ux-design 设计 Windows 桌面应用，先制作 HTML 交互原型供客户确认，再按项目实际采用 WinUI、PySide 或 PyQt 实现。"
+  default_prompt: "使用 $windows-ui-ux 设计 Windows 桌面应用，先制作 HTML 交互原型供客户确认，再按项目实际框架选择 WinUI、Qt/PySide/PyQt 或 Gio 实现。"

references/adapter-gio.md

@@ -0,0 +1,135 @@
+# Go Gio Windows 桌面适配指南
+
+## 目录
+
+1. 版本与适用边界
+2. 即时模式架构与状态
+3. Windows 视觉与布局
+4. 核心交互模式映射
+5. 文件、异步与长任务
+6. 键盘、焦点与无障碍
+7. 构建、测试与交付
+8. 常见反模式
+9. 官方资料
+
+## 1. 版本与适用边界
+
+生成代码前读取 `go.mod`、`go.sum`、入口文件和实际使用的 `gioui.org` 子包，确认 Go、Gio 与扩展包的准确版本。Gio 模块仍是 v1 之前版本，次版本可能包含不兼容变化；应固定已验证版本，并以该版本的包文档和示例为准。
+
+Gio 适合需要 Go 单一技术栈、自绘界面、跨平台渲染和高度定制交互的桌面应用。它不会自动提供完整的 Windows Fluent 控件集，也没有与 WinUI `DataGrid`、`TabView`、`ContentDialog` 或 Mica 一一对应的内置组件。选择 Gio 意味着项目需要明确承担复合控件的状态、输入、焦点、语义、主题和测试成本。
+
+## 2. 即时模式架构与状态
+
+Gio 使用即时模式：应用读取窗口事件、更新持久状态，再在每个 `FrameEvent` 中布局并绘制当前帧。不能依赖上一帧留下的控件对象树。
+
+- `widget.Clickable`、`widget.Editor`、列表位置、标签选择、筛选值和弹层状态等必须由页面或组件结构体长期持有，不能在每一帧的布局函数中重新创建。
+- 领域数据与 UI 交互状态分离。记录以稳定 ID 识别，不以可见标题、排序后的行号或循环索引作为业务身份。
+- 布局函数应接近纯函数：读取状态、消费本帧输入、产生操作；文件、网络、数据库和昂贵计算放在布局循环之外。
+- 将导入、刷新、生成、更新、提交等动作建模为集中命令，统一管理启用条件、执行中、防重复、取消、结果和错误，不要只散落在 `Clicked()` 分支中。
+- 通过显式页面状态描述空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限拒绝和部分结果。
+
+窗口事件循环必须处理 `FrameEvent` 与 `DestroyEvent`，并保证每个帧事件都完成提交。后台结果到达时更新线程安全的应用状态并调用 `Window.Invalidate()` 请求重绘；不要用忙循环持续刷新。
+
+## 3. Windows 视觉与布局
+
+`widget/material` 提供 Material Design 主题和样式，它不是 Windows Fluent 设计系统。Windows 项目应在 Gio 上建立一层薄的设计适配：集中定义语义颜色、字体、字号、间距、圆角、描边、阴影、状态层、图标和动效，再用这些 Token 组合组件。不要在各页面直接散布颜色和尺寸常量。
+
+- Windows 字体优先使用系统可用的 Segoe UI Variable/Segoe UI，并准备缺失时的回退；验证中文字体与混排。
+- 保留系统装饰窗口和标准关闭、最大化、最小化、调整大小行为。不要仅为“像 WinUI”而自制整套非客户区。
+- 不宣称 Gio 内置原生 Mica/Acrylic。只有在隔离的 Windows 原生适配经过版本、性能、高对比度和失效测试后才启用，并始终提供纯色主题表面回退。
+- 以 `layout.Context` 的 `Constraints` 决定紧凑、中等和宽布局，用 `layout.Flex`、`layout.Stack`、`layout.Inset` 和 `layout.List` 组合，不按全屏分辨率或固定像素坐标布局。
+- 在断点切换时保留输入、焦点、选择、勾选、筛选、滚动、展开、任务和未保存状态。
+
+主题至少覆盖浅色、深色、高对比度或可访问的强对比回退，并验证系统强调色不可用、透明效果关闭和远程桌面等场景。颜色不能成为错误、选择或状态的唯一线索。
+
+## 4. 核心交互模式映射
+
+### 导航与标签
+
+Gio 没有内置完整 `NavigationView`/`TabView` 体验。用稳定页面 ID 维护顶级导航，用稳定标签 ID 维护文档工作区，并自行定义：键盘切换、焦点返回、关闭、重排、溢出、未保存确认、任务归属和状态恢复。标签标题只是显示文本，不能作为身份。
+
+### 数据表格
+
+大型表格使用 `layout.List` 或经过测量的自定义虚拟化行布局，只绘制可见区域，避免为每个单元格长期持有昂贵对象。列宽、表头、滚动、固定列和编辑行为需形成单独组件契约。
+
+必须分别建模：
+
+- 当前行/单元格；
+- 键盘焦点；
+- 选择集；
+- 勾选集。
+
+指针命中后先解析稳定记录 ID，再处理单击选择、双击默认操作、右键上下文目标、复选框和行内按钮。双击不能额外执行一次单击的破坏性动作；复选框或行内按钮消费事件后不能继续触发行默认操作。Ctrl/Shift 多选、Space 切换、Enter 调用、上下文菜单键或 Shift+F10 都要有明确规则。排序和筛选后按 ID 恢复有效状态，并向用户说明被筛选隐藏的勾选项。
+
+### 表单
+
+用持久的 `widget.Editor`、布尔/枚举选择状态和应用层字段模型构造表单。每个字段定义标签、说明、必填、格式、领域规则、验证时机、错误位置和提交模式。提交失败保留输入并将焦点移到首个错误；异步验证以请求 ID 或取消机制忽略旧结果。占位文本不能代替字段标签。
+
+### 对话框、反馈与任务
+
+Gio 中的对话框、浮层、信息条通常需要应用自行组合。模态层必须限制背景交互、建立正确绘制层级、将焦点移入、支持 Escape/关闭规则，并在关闭后将焦点返回触发点。只有不可逆、高代价或没有安全默认值的决定才阻塞确认。
+
+普通成功使用内联状态或非阻塞通知；可恢复错误保留上下文并提供重试；长任务在页面内显示阶段、进度、取消和结果。不要为每次生成、更新或提交统一弹出成功对话框。
+
+### 多 Tab 数据工作台
+
+所有工作标签复用同一页面骨架：标题与说明、导入/配置/刷新等顶部前置命令、来源与校验状态、可伸展表格主区、选择摘要，以及生成/更新/提交等底部完成命令。每个命令显式绑定作用域、前置条件、风险、可逆性、确认策略和完成反馈。
+
+## 5. 文件、异步与长任务
+
+文件选择可使用 `gioui.org/x/explorer`，但必须遵循其窗口生命周期：每个窗口创建对应 `Explorer`，将窗口事件传给 `ListenEvents`，并从独立 goroutine 调用阻塞的 `ChooseFile`、`ChooseFiles` 或 `CreateFile`。返回句柄按 `io.Reader`、`io.Writer` 或相关接口使用，不要假设一定是 `*os.File` 或具有普通文件路径。
+
+- goroutine 不直接无同步地修改布局正在读取的复合状态；通过 channel、互斥保护的结果或项目统一状态容器交接。
+- I/O、网络、数据库与计算任务不得阻塞窗口事件循环。
+- 长任务使用 `context.Context` 或等价取消协议，携带任务 ID，并在窗口关闭、标签关闭或新请求替代旧请求后丢弃过期结果。
+- 任务提交阶段要定义幂等性；不能幂等时在进行中禁用重复命令并清楚显示原因。
+- 后台状态改变后调用 `Window.Invalidate()`，不要依赖用户移动鼠标才看到结果。
+
+## 6. 键盘、焦点与无障碍
+
+用 `key.Filter` 声明需要接收的键事件，用 `key.FocusCmd` 请求焦点，并处理焦点进入、离开和方向移动。快捷键的作用域必须清晰；重复操作提供 Windows 常用快捷键或可发现的替代路径。所有仅右键、悬停、拖拽或触控可达的功能都需要键盘路径。
+
+使用 `io/semantic` 为自定义组件公开合适的类别、标签、说明、启用、选择及其他状态。复合表格、标签、对话框和自绘输入承担比标准控件更高的语义责任；代码中存在语义操作不代表屏幕阅读器体验已正确，必须用 Windows Narrator 和无障碍检查工具执行真实任务测试。
+
+焦点指示必须在浅色、深色与强对比背景上清晰；弹层打开和关闭、标签切换、删除当前记录、筛选后当前项消失时都要定义焦点落点。状态变化与错误需要可感知的文本和语义反馈，不能只改变颜色或播放动画。
+
+## 7. 构建、测试与交付
+
+Windows GUI 发布构建可按项目需要使用 `-ldflags="-H windowsgui"` 隐藏控制台，但开发构建应保留可诊断日志。锁定 Go/Gio/扩展模块版本，保存可复现构建命令，并在干净 Windows 环境验证产物、资源、字体、图标与文件选择器。
+
+最低测试矩阵包括：最低支持 Windows 与当前 Windows 11；紧凑/中等/宽窗口、贴靠、最大化和多显示器；100%/125%/150%/200% 缩放；浅色、深色、强对比回退；键盘、鼠标及声明支持的触控；Narrator；空、真实、超大、错误、权限拒绝和慢任务数据；窗口/标签关闭、取消、重试和恢复。
+
+交付前确认：
+
+- [ ] 所有持久 Widget 状态未在帧布局中意外重建。
+- [ ] 页面、标签和记录使用稳定 ID，而非索引或标题。
+- [ ] 大型列表/表格只布局可见内容，并以真实数据测量。
+- [ ] 后台任务不阻塞事件循环，状态同步无数据竞争，结果到达会触发重绘。
+- [ ] 键盘、焦点、语义、对话框和上下文菜单已用真实辅助技术验证。
+- [ ] Windows 视觉层使用集中 Token，且有纯色和强对比回退。
+- [ ] 依赖版本、构建命令和自定义复合控件责任已记录。
+
+## 8. 常见反模式
+
+- 每帧重新创建 `widget.Clickable`、`widget.Editor` 或列表状态，导致输入和焦点丢失。
+- 把 `widget/material` 的默认外观直接称为 Windows Fluent。
+- 在事件循环中执行阻塞 I/O，或用持续重绘掩盖状态同步问题。
+- 用排序后行号保存勾选或选择，导致筛选后作用于错误记录。
+- 自绘表格、标签或弹层，却没有键盘、焦点、语义和屏幕阅读器测试。
+- 假设 `x/explorer` 返回本地路径或 `*os.File`，或者在帧处理 goroutine 中调用其阻塞选择方法。
+- 为视觉效果移除系统窗口能力，或把未经验证的 Windows 私有 API 变成必需依赖。
+
+## 9. 官方资料
+
+- [Gio 架构](https://gioui.org/doc/architecture)
+- [Gio Widget 架构](https://gioui.org/doc/architecture/widget)
+- [窗口事件与重绘](https://gioui.org/doc/architecture/window)
+- [输入处理](https://gioui.org/doc/architecture/input)
+- [布局系统](https://gioui.org/doc/architecture/layout)
+- [layout 包](https://pkg.go.dev/gioui.org/layout)
+- [widget 包](https://pkg.go.dev/gioui.org/widget)
+- [Material 组件包](https://pkg.go.dev/gioui.org/widget/material)
+- [键盘输入包](https://pkg.go.dev/gioui.org/io/key)
+- [语义无障碍包](https://pkg.go.dev/gioui.org/io/semantic)
+- [窗口 app 包](https://pkg.go.dev/gioui.org/app)
+- [文件选择 explorer 包](https://pkg.go.dev/gioui.org/x/explorer)

references/adapter-qt.md

@@ -1,4 +1,4 @@
-# Windows 上的 PySide/PyQt 工程指南
+# Windows Qt / PySide / PyQt 适配指南
 
 ## 目录
 
@@ -71,6 +71,18 @@
 
 Qt Quick/QML 项目使用 Qt Quick Controls 的等价语义控件，并为 Python 暴露的状态使用 `Signal`、`Slot` 和带通知信号的 `Property`。不要把 QWidget 嵌入 QML 作为常规布局方案。
 
+### 核心交互模式映射
+
+**数据表格：** 使用 `QTableView`、自定义 `QAbstractTableModel` 与 `QSortFilterProxyModel`，以稳定记录 ID 维护业务选择和勾选状态。`currentIndex()`、`selectionModel()` 与模型中的勾选角色分别对应当前单元格、选择集和勾选集，不能互相替代。通过视图的 `clicked`、`doubleClicked`、`activated` 与 `customContextMenuRequested` 明确区分单击、双击、键盘调用和右键；右键先解析目标索引，再按产品规则决定是否改变选择。复选框和行内按钮的委托事件必须停止继续触发行默认操作。
+
+**表单：** 使用标准编辑控件、`QFormLayout`、标签 Buddy 和字段旁固定错误区。格式约束可用 `QValidator` 或输入掩码，领域规则仍由应用层验证。避免在每次按键后弹框；提交失败时保留输入，聚焦首个错误，并给出问题与修复方式。异步验证以请求 ID 或取消机制忽略过期结果。
+
+**导航与标签：** 顶级导航可用 Model 驱动的 `QListView` 配合 `QStackedWidget`；文档工作区使用 `QTabWidget`，或以 `QTabBar` 加内容容器构建。页面与标签都用稳定 ID 管理，不以标题或当前索引作为业务身份。关闭、重排和切换前定义未保存检查、焦点返回、筛选/选择/滚动恢复及后台任务所有权。
+
+**对话框与任务：** `QDialog`/`QDialogButtonBox` 只承载必须阻塞的决策；普通状态与可恢复错误使用页面内 Banner、状态区或非模态面板。长任务由 worker 或线程池执行，通过队列信号回传进度与结果，并支持取消、重复提交防护、关闭后忽略回调及成功/失败/重试状态。
+
+**多 Tab 数据工作台：** 每个页面统一采用垂直布局：标题与说明、顶部 `QToolBar`/命令区、来源或校验状态区、可伸展的 `QTableView` 主区、底部选择摘要与完成操作区。将同一 `QAction` 复用于按钮、菜单和快捷键。普通成功不弹 `QMessageBox`；只有不可逆、高代价或缺少安全默认值的操作才在执行前确认。
+
 ## 3. 架构、对象生命周期与数据模型
 
 ### 对象与职责

references/adapter-winui3.md

@@ -1,4 +1,4 @@
-# WinUI 控件与桌面端模式
+# WinUI 3 / Windows App SDK 适配指南
 
 ## 目录
 
@@ -9,8 +9,10 @@
 5. 命令与菜单
 6. 反馈与临时界面
 7. 常见页面模式
-8. 控件评审检查清单
-9. 官方资料
+8. XAML 工程与版本门槛
+9. 多 Tab 数据工作台映射
+10. 发布验证与评审
+11. 官方资料
 
 ## 1. 选择方法
 
@@ -140,7 +142,40 @@ Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+
 
 说明发生了什么、已知时说明原因，以及用户下一步能做什么。区分空状态：首次使用为空、筛选后为空、权限被拒绝、断开连接和加载失败是不同问题。
 
-## 8. 控件评审检查清单
+## 8. XAML 工程与版本门槛
+
+生成 XAML 或 C# 前，读取项目文件、中央软件包属性、目标框架、Windows App SDK 与 Toolkit 版本、最低 Windows 版本及打包模型。WinUI 3 使用 `Microsoft.UI.Xaml`；`Windows.UI.Xaml`、WinUI 2 Gallery 和 UWP 示例只能作为迁移参考，不能直接复制。
+
+版本敏感能力必须注明最低版本与回退策略。例如，WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本，`SystemBackdropElement` 需要 1.6.3 或更高版本，Mica 在 Windows 10 上必须回退为可读的纯色主题表面。任何第三方控件还要记录版本、许可证、维护状态、主题、高对比度、UI Automation、键盘、虚拟化和退出方案。
+
+- 遵循项目既有 MVVM 或代码隐藏约定，不为一个页面引入第二套架构。
+- 用可复用命令统一按钮、菜单、上下文菜单和快捷键；异步命令需防重复提交。
+- 在资源字典中集中管理语义颜色、文本、间距、圆角、图标与动效；运行时主题值使用 `ThemeResource`。
+- 优先使用样式与组合。替换完整控件模板意味着同时承担视觉状态、输入、焦点和无障碍责任。
+- 使用 `Grid` 与弹性尺寸构造响应式布局；避免深层嵌套和无法承受本地化、文本缩放的固定尺寸。
+- 保持集合虚拟化，不在 UI 线程执行同步文件、网络、数据库或昂贵序列化工作。
+- 长任务支持取消；导航、查询变化或窗口关闭后忽略过期结果，只把必要的最终状态更新封送回 UI 线程。
+
+标题栏必须保留系统标题按钮、系统菜单和有效拖动区域，并验证最大化、还原、调整大小、Snap Layouts、活动/非活动、高对比度及右键系统菜单。多窗口必须明确所有者、激活、持久化位置、共享数据生命周期和对话框的 `XamlRoot`。
+
+## 9. 多 Tab 数据工作台映射
+
+对“顶部前置操作—中部表格—底部完成任务”的页面，使用统一页面骨架：
+
+```text
+Grid Rows="Auto,Auto,*,Auto,Auto"
+  页面标题/说明
+  CommandBar：导入、配置、刷新、筛选
+  状态区：InfoBar、来源摘要、校验结果
+  数据区：虚拟化列表/表格、加载/空/错误覆盖层
+  底部操作区：选择摘要、次要操作、主要生成/更新/提交
+```
+
+静态功能切换使用 `SelectorBar` 或适合内容的选择器；可关闭、可重排、具有独立工作状态的文档工作区使用 `TabView`。每个标签以稳定 ID 保存数据来源、筛选、排序、选择、勾选、滚动、验证、任务和未保存状态，不能以可见标题作为身份。
+
+文件选择使用与项目打包模型和 Windows App SDK 版本相符的文件选择器，并在编码前验证窗口初始化要求。进行中状态优先在页面内显示；可恢复错误用 `InfoBar`；只有不可安全自动决定、不可逆或代价高的操作才使用 `ContentDialog`。普通成功以内联状态、状态栏或非阻塞通知反馈，避免统一弹出成功对话框。
+
+## 10. 发布验证与评审
 
 - [ ] 每个控件都匹配用户意图并公开正确语义。
 - [ ] 所有 API 和依赖项都存在于项目使用的版本中。
@@ -150,8 +185,15 @@ Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+
 - [ ] 表单保留输入并提供可操作的验证信息。
 - [ ] 对话框仅用于真正需要阻塞的决策。
 - [ ] 已处理加载、空、错误、超时、取消和撤销状态。
+- [ ] 主题资源可运行时更新，并覆盖浅色、深色和高对比度。
+- [ ] 标题按钮、拖动区域、窗口所有权和对话框 `XamlRoot` 正确。
+- [ ] 生产规模数据下的虚拟化、回收、取消和过期结果处理有效。
 
-## 9. 官方资料
+至少验证最低支持 Windows 与当前 Windows 11、紧凑/中等/宽窗口、贴靠和最大化、100%/125%/150%/200% 缩放、默认与增大文本、浅色/深色/高对比度、透明效果开关、键盘/鼠标及声明支持的触控、Narrator、真实与超大数据、空/错误/权限拒绝，以及辅助窗口关闭和恢复。自动测试不能替代焦点、播报、动效、文案和感知响应速度的人工评审。
+
+按以下优先级报告问题：阻断（主要任务、数据、安全或无障碍不可用）、严重（频繁错误或主要性能/响应式问题）、中等（效率和平台一致性下降）、轻微（低影响视觉润色）。每项必须指出触发条件、用户影响和最小稳健修正。
+
+## 11. 官方资料
 
 - [Windows 应用控件](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
 - [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
@@ -161,3 +203,8 @@ Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+
 - [对话框与浮出控件](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
 - [应用设置指南](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
 - [已归档 WCT DataGrid 状态](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
+- [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
+- [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
+- [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
+- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
+- [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)

references/core-data-table.md

@@ -0,0 +1,198 @@
+# 桌面数据表格交互规范
+
+## 目录
+
+1. 适用范围与交互契约
+2. 状态模型
+3. 指针事件与优先级
+4. 筛选、排序与搜索
+5. 勾选、多选与批量操作
+6. 键盘与无障碍
+7. 数据变化、分页与虚拟化
+8. 视觉与反馈
+9. 测试矩阵
+10. 交付检查清单
+
+## 1. 适用范围与交互契约
+
+为展示结构化多列数据且支持选择、筛选、操作或编辑的表格、网格和高密度列表使用本规范。只读报表也要定义排序、复制、焦点和空状态；可编辑数据网格还要定义验证、提交和撤销。
+
+在设计或编码前写出交互契约，至少回答：
+
+- 选择单位是整行、单元格还是列；支持单选、连续多选还是非连续多选；
+- 复选框代表“批量选择”还是一个真实业务字段；
+- 单击行只选择，还是还会导航、展开或编辑；
+- 双击行执行默认命令、进入编辑，还是禁用；
+- 右键未选中行与已选中行时，命令作用于哪一组对象；
+- 筛选作用于本地数据、当前页、已加载数据还是服务端完整结果；
+- 排序、筛选、刷新、分页后是否保留选择和勾选；
+- 主键、权限和数据变化如何使已有选择失效；
+- 每个鼠标操作对应什么键盘和无障碍操作。
+
+若产品未指定，采用本规范的推荐默认值。不要把框架初始属性当作已经确认的产品行为。
+
+## 2. 状态模型
+
+### 分离四类状态
+
+| 状态 | 含义 | 推荐规则 |
+|---|---|---|
+| 当前行/当前单元格 | 后续键盘命令的目标和导航位置 | 同一表格通常只有一个；刷新后尽量保持稳定主键 |
+| 键盘焦点 | 当前接收键盘输入的元素 | 必须始终可见；可能在单元格内按钮或编辑器上 |
+| 选择集 | 详情、上下文命令或批量操作的对象 | 使用稳定记录 ID，不使用视图行号 |
+| 勾选集 | 选择复选框或业务布尔字段的值 | 先确定语义；不得默认等同选择集 |
+
+### 选择复选框与业务复选框
+
+- **选择复选框：** 复选框只是多选的可见入口，勾选集与选择集是同一状态；表头复选框控制明确范围内的选择。
+- **业务复选框：** 复选框表示“启用”“已审核”等领域字段，与行选择完全独立；列标题必须表达业务含义，不使用无标签的选择列样式。
+- 同一表格同时需要两者时使用不同列、不同标题/工具提示和不同视觉反馈，并在规格中分别命名。
+- 不要让整行单击切换业务复选框。不要维护两个看似相同但可能不同步的选择数组。
+
+### 状态不变量
+
+- 排序和筛选改变视图顺序，不改变记录 ID。
+- 当前行可以未被多选；选中行也不一定拥有单元格焦点。
+- 失效、无权限或被删除的记录必须从操作集合移除并告知用户。
+- 行号只用于展示位置，不能作为选择、缓存、编辑或命令参数。
+- 视觉上区分 hover、当前、焦点、选中、勾选、编辑、错误和禁用状态。
+
+## 3. 指针事件与优先级
+
+### 推荐交互矩阵
+
+| 输入 | 目标 | 推荐结果 |
+|---|---|---|
+| 左键单击 | 行的非交互区域 | 将该行设为当前行；无修饰键时单选，Ctrl 切换，Shift 从锚点范围选择 |
+| 左键单击 | 选择复选框 | 切换该行选择状态；更新当前行，但不触发行默认操作 |
+| 左键单击 | 业务复选框 | 仅切换/提交该字段；不触发行默认操作，选择是否变化须显式规定 |
+| 左键单击 | 按钮、链接、菜单或编辑器 | 仅执行该控件行为；事件不得冒泡成行操作 |
+| 左键双击 | 行的非交互区域 | 执行唯一的非破坏性默认命令，或按契约进入编辑 |
+| 右键/长按 | 未选中行 | 将其设为当前且唯一选中行，再打开针对该行的上下文菜单 |
+| 右键/长按 | 已选中行 | 保留现有多选，打开针对整个选择集的菜单 |
+| 右键 | 空白区域/表头 | 不借用旧行上下文；显示表格级/列级菜单或不显示菜单 |
+
+### 事件优先级
+
+按“单元格内控件 → 编辑器 → 行 → 表格空白区域”处理命中目标，内层处理后阻止外层重复执行。不得使用任意延时猜测单击还是双击。
+
+单击行只负责当前项和选择，不执行打开、删除、提交等业务副作用。这样双击产生的两次单击不会重复执行业务命令。双击仅在同一有效记录的非交互区域触发；滚动条、复选框、按钮、链接、输入框和空白区不得触发。
+
+双击默认命令必须满足：
+
+- 非破坏性，通常是打开详情、预览或开始编辑；
+- 同时提供 Enter、显式按钮或菜单入口；
+- 与内联编辑的双击触发二选一，不同时绑定；
+- 数据变化后按稳定 ID 再次确认目标仍存在且允许操作。
+
+上下文菜单打开前先解析命中行和有效选择集。命令文案、启用状态和作用对象数量必须一致；菜单关闭不清除选择。提供 Shift+F10、菜单键或可见命令入口。
+
+## 4. 筛选、排序与搜索
+
+### 筛选模型
+
+- 明确全局搜索、列筛选、固定范围筛选和高级条件之间是 AND 还是 OR。
+- 按字段类型提供合适运算：文本包含/等于，数字和日期范围，枚举多选，布尔三态，空值/非空。
+- 显示每个活动筛选、结果数量和“清除全部”；仅靠输入框内容或列标题颜色不足以表达状态。
+- 区分“无数据”与“筛选后无结果”，后者保留条件并提供清除入口。
+- 定义大小写、重音、全半角、区域设置、时区、空白和无效输入规则。
+- 本地筛选保持界面即时；服务端筛选使用防抖、取消或请求 ID，忽略过期响应并显示加载/错误状态。
+- 筛选条件变化通常返回第一页或合适的首个结果，同时避免让焦点跳回页面顶部。
+
+### 排序
+
+- 表头明确未排序、升序和降序；向无障碍 API 暴露排序状态。
+- 多列排序必须显示优先级；不支持时只保留一个排序键。
+- 使用稳定排序，定义空值位置和区域感知比较。
+- 排序后按记录 ID 保持当前项、选择和未提交编辑，不按旧行号恢复。
+
+### 筛选与选择的关系
+
+默认保留被筛选隐藏的已选记录，并在批量工具栏显示“已选 N 项，其中 M 项当前不可见”，同时提供仅清除隐藏选择或清除全部。若业务要求筛选即清除选择，必须在操作发生前明确提示并保持一致。
+
+表头全选必须标明范围：当前可见页、当前已加载结果，或所有符合筛选的结果。跨服务端完整结果选择时使用“筛选条件 + 排除 ID”或后端选择令牌等模型，不要假装客户端已持有所有 ID。
+
+## 5. 勾选、多选与批量操作
+
+- 选择复选框列固定在行首，表头使用三态：无、部分、全部；状态以已声明的全选范围计算。
+- 点击表头全选前后都应让范围可理解，例如“选择本页 50 项”或“已选择全部 2,418 个匹配项”。
+- Ctrl 支持独立增减选择，Shift 使用上次选择锚点扩展范围；筛选、排序后锚点无效时安全重置。
+- 批量工具栏显示选择数量，只提供所有选中记录共同允许的命令。
+- 对危险批量操作显示准确对象数和影响；可恢复操作优先支持撤销。
+- 处理部分成功：列出成功、失败、跳过和权限不足的数量，允许重试失败项。
+- 选择数很大时不要为每个 ID 创建 Widget 或重复复制完整对象；存储 ID/选择表达式。
+- 禁用行仍可按需求查看，但不可勾选或执行命令；说明禁用原因。
+
+## 6. 键盘与无障碍
+
+### 键盘基线
+
+| 按键 | 推荐行为 |
+|---|---|
+| 上/下方向键 | 移动当前行；是否同时改变选择取决于选定的选择模式 |
+| 左/右方向键 | 单元格导航，或在行模式下滚动/进入单元格控件 |
+| Ctrl+Space | 切换当前行的多选状态 |
+| Shift+方向键/单击 | 从选择锚点扩展连续范围 |
+| Ctrl+A | 选择明确定义的当前范围；大规模/服务端数据需二次表达全量范围 |
+| Space | 当前焦点为复选框时切换它；不得同时触发行默认操作 |
+| Enter | 执行与双击相同的默认命令，或提交当前编辑 |
+| F2 | 进入可编辑单元格；与双击编辑契约保持一致 |
+| Escape | 取消菜单/编辑；再次按键是否清除选择须明确规定 |
+| Shift+F10/菜单键 | 为当前行或选择集打开上下文菜单 |
+
+### 无障碍
+
+- 为表格提供可感知名称、列标题、行/列关系、排序状态、选择状态、复选状态和总数/可见数。
+- 焦点与选择使用不同视觉信号，不只依赖颜色。
+- 复选框、按钮和链接使用其真实控件语义与名称；不要让整个数据行伪装成多个按钮。
+- HTML 静态数据优先使用原生 `<table>`。只有实现完整二维键盘导航时才使用交互式 `grid` 语义，并采用 roving tabindex 或 `aria-activedescendant`。
+- 表格发生筛选、批量完成或错误时，以不过度打扰的方式播报结果数量和状态变化。
+- 高对比度、200% 缩放和长文本下仍能辨认当前行、选中、勾选、编辑和错误状态。
+
+## 7. 数据变化、分页与虚拟化
+
+- 所有交互状态关联稳定记录 ID；代理模型、排序、筛选和虚拟化层必须能映射回源记录。
+- 刷新时保留仍存在且仍有权限的当前项与选择；不存在的项从集合移除并反馈。
+- 编辑期间收到远程更新时定义覆盖、合并、冲突或刷新策略，不得静默丢失输入。
+- 分页、增量加载和虚拟滚动不得导致复选状态闪烁、重复触发命令或焦点落到另一条记录。
+- 服务端操作携带筛选、排序、页游标和请求 ID；只应用最新有效响应。
+- 行命令启动后防止重复提交，显示行级或批量进度，并支持合理取消。
+- 大型表格保持虚拟化；不要在每个单元格嵌入常驻复杂控件。
+
+## 8. 视觉与反馈
+
+- 表头固定或滚动时保持列对应关系；列宽、截断、换行和水平滚动策略必须明确。
+- 当前行、选择、勾选与焦点各有可区分状态，但避免叠加过多高饱和背景。
+- 可排序列显示方向；可筛选列显示入口和活动状态；不要只在 hover 时显示关键筛选信息。
+- 批量操作栏出现时不遮挡表头、分页或最后几行，并保持选择数量可见。
+- 行内错误靠近相关单元格，同时提供行级摘要；不要仅用红色边框。
+- 加载骨架不得伪装成可选行；刷新时避免清空整个表格造成焦点和滚动跳动。
+- 空状态区分首次无数据、筛选无结果、权限不足、加载失败和离线缓存。
+
+## 9. 测试矩阵
+
+至少验证：
+
+1. 单选、多选、Ctrl、Shift、表头全选和三态复选框；
+2. 单击、双击、右键、长按以及单元格内复选框/按钮/链接/编辑器；
+3. 右键未选中行、已选中行、空白区和表头；
+4. Enter、F2、Space、Ctrl+Space、Ctrl+A、Shift+F10、Escape 和方向键；
+5. 筛选后无结果、多个条件、清除全部、服务端延迟、失败和过期响应；
+6. 排序、筛选、刷新、分页和虚拟滚动后的当前项、选择、勾选及焦点；
+7. 删除选中项、权限变化、部分成功、重复提交和窗口提前关闭；
+8. 0、1、少量、大量和超大数据，长文本、空值、重复显示值和稳定 ID；
+9. 浅色、深色、高对比度、100%–200% 缩放、键盘和屏幕阅读器；
+10. 原型与最终桌面实现使用同一交互契约的对照验收。
+
+## 10. 交付检查清单
+
+- [ ] 已定义行/单元格选择模式及当前项、焦点、选择集、勾选集的关系。
+- [ ] 已明确复选框是选择入口还是业务字段。
+- [ ] 单击、双击、右键和单元格内控件不会重复触发行默认命令。
+- [ ] 右键目标、多选保留和键盘上下文菜单行为明确。
+- [ ] 筛选运算、服务端/本地范围、空值、结果数和清除入口完整。
+- [ ] 表头全选范围、隐藏选择、三态和大规模全选模型明确。
+- [ ] 排序、筛选、刷新、分页和虚拟化均使用稳定 ID 保持状态。
+- [ ] 鼠标功能具有键盘、触控和无障碍等价路径。
+- [ ] 原型与最终桌面实现已按测试矩阵验证，而非只检查静态视觉。
+- [ ] 组件/API 已按项目准确版本验证。

references/core-data-workspace.md

@@ -0,0 +1,285 @@
+# 桌面多 Tab 数据工作台布局与命令分区规范
+
+## 目录
+
+1. 适用范围与设计目标
+2. 先验证 Tab 模型
+3. 统一页面骨架
+4. 命令分类与放置
+5. 跨 Tab 一致性
+6. 文件导入与前置条件
+7. 表格主工作区
+8. 底部完成任务区
+9. 执行前确认策略
+10. 执行中与完成反馈
+11. 状态与生命周期
+12. 响应式、键盘与无障碍
+13. 测试矩阵与交付检查清单
+
+## 1. 适用范围与设计目标
+
+当 Windows 桌面应用包含多个标签页，并且多个标签页共享“准备数据或导入文件 → 检查/筛选表格 → 生成、更新或提交结果”的任务结构时，使用本规范统一页面布局、命令语义和反馈位置。
+
+统一的目标是让用户学会一个标签页后能够预测其他标签页，而不是让所有页面机械地拥有相同控件。保持以下心智模型稳定：
+
+> 准备数据 → 检查数据 → 完成任务 → 获得结果与恢复入口
+
+设计前记录每个标签页的任务、数据源、前置条件、表格对象、主命令、影响范围和恢复方式。没有表格或没有完成阶段的标签页可以省略对应区域，不得为了视觉对齐保留无意义的空按钮或禁用占位。
+
+本规范只负责页面级组合。标签身份、关闭和状态恢复遵循 `core-navigation-tabs.md`；表格选择、筛选和行事件遵循 `core-data-table.md`；确认、进度和完成反馈遵循 `core-dialogs-tasks.md`；字段与文件选择遵循 `core-form-input.md`。
+
+## 2. 先验证 Tab 模型
+
+- 少量、固定、同一工作对象的同级任务可以使用静态标签。
+- 可创建、关闭、重排且具有独立脏状态的文档使用文档标签。
+- 彼此无关的业务模块优先使用顶级导航，不要仅因页面外观相似就放进同一标签条。
+- 标签过多且用户需要搜索目的地时，改用导航、溢出列表或分组，不把标签压缩到无法识别。
+- 标签文本使用稳定名词或任务名；不要在不同运行阶段反复改变标签名称来表达状态。
+
+在编码前确定标签是静态任务还是文档实例，并为每个标签使用稳定 ID。不要用显示索引绑定数据源、保存目标或任务状态。
+
+## 3. 统一页面骨架
+
+默认使用以下垂直区域。`Auto` 区域按内容占用空间，表格区使用剩余空间；反馈区和完成区不得覆盖表头、分页或最后一行。
+
+```text
+┌──────────────── 标签栏 ────────────────┐
+│ 页面标题 / 数据源摘要 / 页面状态          │  可选，Auto
+├─────────────────────────────────────────┤
+│ 导入文件  前置参数  校验  刷新  更多命令   │  数据准备区，Auto
+├─────────────────────────────────────────┤
+│ 搜索  筛选  结果数  清除条件  视图命令     │  表格命令区，Auto
+├─────────────────────────────────────────┤
+│                                         │
+│                 数据表格                │  主工作区，*
+│                                         │
+├─────────────────────────────────────────┤
+│ 已选 N 项 / 进度 / 错误 / 最后更新时间    │  状态反馈区，按需 Auto
+├─────────────────────────────────────────┤
+│                     取消  更新数据  生成   │  完成任务区，按需 Auto
+└─────────────────────────────────────────┘
+```
+
+### 布局规则
+
+- 各标签页复用同一页面外壳组件、内容边距、区域间距、命令高度、主按钮位置和反馈位置。
+- 页面标题仅在标签名不足以说明当前对象或范围时出现；不要无意义重复标签文本。
+- 数据准备区与表格命令区可在内容简单时合并，但命令顺序仍按“来源/前置 → 查看/筛选”排列。
+- 表格是主要工作区时必须获得剩余高度，不用固定高度让窗口下方产生大片空白。
+- 状态反馈区采用稳定插入位置。出现错误、进度或选择工具栏时避免让表格和底部按钮剧烈跳动。
+- 完成任务区仅在页面存在明确提交阶段时显示；只读、浏览或仅刷新页面可以省略。
+
+## 4. 命令分类与放置
+
+先为命令确定作用域，再决定位置。相同命令跨菜单、工具栏、上下文菜单和快捷键复用同一命令状态，不复制业务逻辑。
+
+| 命令类型 | 典型命令 | 首选位置 |
+|---|---|---|
+| 应用/窗口级 | 新建窗口、全局设置、帮助 | 应用外壳、菜单或全局工具栏 |
+| 数据来源 | 选择文件、导入、重新导入、连接数据源 | 页面上方的数据准备区 |
+| 前置配置 | 输出目录、模板、规则、日期范围 | 数据准备区；复杂时使用侧面板或任务页 |
+| 表格视图 | 搜索、筛选、排序、列设置、刷新列表 | 紧邻表格上方 |
+| 行对象 | 打开详情、预览、编辑单行 | 行内可见入口、上下文菜单或表格命令区 |
+| 选择集/批量 | 删除所选、批量修改、导出所选 | 选择后出现的批量工具栏，显示对象数量 |
+| 工作流完成 | 生成、应用全部更新、提交、发布 | 页面底部完成任务区 |
+| 低频辅助 | 查看日志、导入历史、高级设置 | 更多/溢出菜单或辅助面板 |
+
+### 命令语义
+
+- 使用具体动词和对象，如“刷新列表”“更新 28 条记录”“生成报告”，不要让“更新”同时表示重新加载和写入数据。
+- 每个局部任务区域最多使用一个视觉主按钮。底部完成区通常只突出当前工作流的最终安全操作。
+- 相同位置保持相同语义；不要让一个标签页底部的“更新”保存数据，另一个标签页同位置的“更新”仅刷新视图。
+- 破坏性命令与常规主操作分开，不把“永久删除”紧邻“生成”且使用相同样式。
+- 高频命令保持可见；右键、悬停、拖放和手势只能作为加速路径。
+- 不适用的命令直接省略。因权限、缺少前置条件或任务运行而禁用时，提供可发现的原因。
+
+为每个命令定义以下契约：
+
+```text
+command_id
+label_and_object
+scope: app | page | table | selection | row
+target_ids_or_query
+prerequisites
+placement
+enabled_reason / disabled_reason
+reversible
+confirmation_policy
+task_mode: immediate | foreground | background
+completion_feedback
+shortcut_or_access_key
+```
+
+## 5. 跨 Tab 一致性
+
+统一以下内容：
+
+- 页面区域顺序、外边距、间距 Token、控件高度、图标语言和按钮层级；
+- 同类命令的名称、图标、相对顺序、快捷键、启用条件和进度表达；
+- 表格的表头、选择、焦点、勾选、筛选活动态、空状态和错误状态；
+- 主操作靠右或项目既定位置，状态与对象数量位于稳定的次要区域；
+- 加载、取消、成功、失败和部分成功的反馈层级；
+- 标签切换后的状态保留和焦点恢复。
+
+允许以下差异：
+
+- 不同任务需要的前置字段、表格列和次要命令；
+- 由风险、可逆性和影响范围决定的确认策略；
+- 由数据量和任务时长决定的分页、虚拟化和进度形式。
+
+不要用固定按钮宽度强行容纳所有本地化文本。使用最小尺寸、内容自适应和一致的内边距；只在同一命令组确有比较价值时对齐宽度。
+
+## 6. 文件导入与前置条件
+
+### 导入状态
+
+至少区分 `empty`、`selecting`、`validating`、`ready`、`importing`、`imported`、`invalid`、`failed`、`cancelled` 和适用时的 `stale/conflict`。
+
+- 使用平台文件/文件夹选择器；显示最终文件名或路径，以及有助于判断的格式、大小、修改时间或记录数。
+- 用户取消选择器是正常取消，不显示错误。
+- 明确“选择文件”只是选择，还是选择后立即导入。高成本或可能覆盖当前数据时不要隐式开始。
+- “追加导入”“替换当前数据”和“重新导入”使用不同文案，并在执行前说明对筛选、选择、编辑和未提交结果的影响。
+- 文件校验在数据准备区附近显示；错误指出文件、原因和修复办法，不用模态框逐条报告。
+- 拖放可以加速导入，但必须保留可见的选择/导入按钮和键盘路径。
+- 同一标签页再次选择文件时，只有会丢失不可恢复工作才确认；可安全撤销或未产生修改时直接替换并反馈。
+- 导入、解析和校验不得阻塞 GUI 线程。任务运行时防止重复导入，并定义取消后保留或清理哪些结果。
+
+完成任务按钮的可用性由明确前置条件决定，例如：文件有效、必填参数完整、表格无阻断错误、当前选择范围有效且无冲突。禁用按钮附近显示尚缺条件，不仅依靠灰色状态。
+
+## 7. 表格主工作区
+
+- 搜索、筛选、结果数量和清除入口紧邻表格，不能散落到页面底部。
+- 刷新列表属于视图/数据获取命令；写入业务数据的命令命名为“保存更改”“应用更新”等，避免混淆。
+- 当前行、键盘焦点、选择集和勾选集保持独立；批量工具栏显示准确选择数量和隐藏选择数量。
+- 行级命令作用于命中行；批量命令作用于已声明选择集；页面完成命令作用于整个已声明数据范围。执行前再次解析稳定 ID 或筛选表达式。
+- 空、筛选无结果、加载、离线、权限不足、失败和部分数据状态使用不同内容与恢复入口。
+- 切换标签后返回时，按产品价值保留筛选、排序、分页、滚动、当前行、选择和未提交编辑，不默认重置整个表格。
+
+## 8. 底部完成任务区
+
+底部区域用于结束当前页面工作流的命令，不是所有按钮的收纳区。
+
+### 可以放在底部
+
+- 生成最终文件、报告或构建产物；
+- 将已检查的数据应用到业务系统；
+- 提交、发布或完成当前步骤；
+- 与上述主操作直接相关的取消、返回、保存草稿或预览。
+
+### 不应放在底部
+
+- 选择/导入文件、刷新列表、清除筛选和列设置；
+- 只作用于单行的打开、编辑和删除；
+- 只作用于当前选择集的高频批量命令；
+- 与当前任务无关的设置、帮助和日志入口。
+
+### 布局与状态
+
+- 保持主操作位置稳定，通常位于完成区末端；次操作在其前，危险操作分组或移入明确菜单。
+- 左侧可显示数据范围、脏状态、阻断原因、进度或最后完成时间，但不要重复上方已有信息。
+- 固定/粘性完成区只能固定在标签页内容边界内，不遮挡表格滚动条、分页或最后一行。
+- 窗口变窄时先让次要命令进入溢出或分行，再保证主操作和取消入口可见。
+- 任务开始后禁用重复提交；主按钮可以显示当前阶段，但宽度变化不能造成明显位移。
+- 切换标签、关闭标签或窗口时，明确任务继续后台、取消还是阻止离开，并与未保存协议一致。
+
+## 9. 执行前确认策略
+
+不得为所有完成命令统一弹出确认框。频繁、无风险的确认会形成自动点击习惯，降低真正高风险确认的价值。
+
+| 策略 | 使用条件 | 示例 |
+|---|---|---|
+| `none` | 可逆、幂等、影响清晰或只是生成预览 | 刷新、重新计算、生成不覆盖的新文件 |
+| `destructive` | 永久删除、覆盖、丢弃不可恢复数据 | 覆盖已有文件、永久删除记录 |
+| `high_impact` | 大批量、外部副作用、成本高或影响难以预见 | 更新数千条记录、发送到外部系统 |
+| `always_required` | 法规、安全、支付、发布或业务明确要求人工决策 | 支付、正式发布、提交审批 |
+
+确认框必须显示动作、对象/范围、数量、不可逆后果和必要条件，按钮使用具体动词。例如使用“取消 / 更新 428 条”，不用“否 / 是”或“取消 / 确定”。不可逆操作默认聚焦安全选项。
+
+可恢复的频繁操作优先直接执行并提供撤销。能在页面内提供预览、差异或范围摘要时，先让用户自然审阅，不再叠加无信息量的确认框。
+
+## 10. 执行中与完成反馈
+
+### 执行中
+
+- 立即提供按下/忙碌反馈，防止双击生成重复任务。
+- 已知总量时显示可信进度和当前阶段；未知时使用不确定进度并说明正在做什么。
+- 只有任务支持安全取消时显示取消。点击后进入“正在取消”，不要立即谎称已取消。
+- 可后台运行的长任务放入稳定任务区；切换标签不应丢失任务所有权或状态。
+
+### 完成后
+
+| 完成情况 | 推荐反馈 |
+|---|---|
+| 页面结果已明显变化 | 不额外弹窗；更新表格、状态或时间 |
+| 保存、复制、导出等结果不明显 | 非模态状态/提示，并提供位置或下一步 |
+| 生成文件 | “已生成 N 个文件 · 打开文件夹/打开结果” |
+| 可撤销操作 | 持久到足以操作的撤销反馈 |
+| 页面级失败或需要恢复 | 持久信息条，提供重试或修复入口 |
+| 部分成功 | 显示成功、失败、跳过数量和“查看/重试失败项” |
+| 用户必须立即决策才能继续 | 结果对话框或任务页 |
+
+不要为普通成功统一弹出模态框。成功对话框会打断连续工作，也会迫使用户执行没有业务价值的“确定”。临时提示不得承载唯一的撤销、错误详情或结果入口。
+
+## 11. 状态与生命周期
+
+每个标签页至少按稳定标签/文档 ID 保存：
+
+```text
+data_source
+prerequisite_values_and_validation
+filter_sort_page
+current_row_id
+selected_ids_or_selection_expression
+scroll_and_focus_target
+dirty_or_conflict_state
+task_id_and_task_state
+last_result_and_recovery_action
+```
+
+- 业务数据、任务状态和临时视图状态分层，不把所有状态塞进页面控件。
+- 标签切换不取消任务、不清空筛选、不覆盖未提交数据；确需重置时由显式命令触发。
+- 异步回调核对任务 ID、标签 ID、数据版本和对象生命周期，过期结果不得写入新标签或新数据源。
+- 文件路径、凭据和敏感数据仅按产品需要持久化，不写入日志、HTML 原型 URL 或不受保护的设置。
+- 权限或数据变化导致目标失效时，停止相应命令、移除无效选择并解释影响。
+
+## 12. 响应式、键盘与无障碍
+
+- Tab 顺序遵循“标签栏 → 数据准备区 → 表格命令区 → 表格 → 状态/完成区”；复杂工作区支持 `F6` 在主要区域间移动。
+- 标签条和表格内部使用方向键；Enter/Space 保持平台控件语义。常用导入、查找、保存和刷新命令可使用 `Ctrl+O`、`Ctrl+F`、`Ctrl+S` 和 `F5`，但仅在语义准确时采用。
+- 仅图标命令提供名称和工具提示；同名按钮在不同标签中增加足够上下文供屏幕阅读器区分。
+- 进度、错误、选择数量和完成结果通过标准无障碍状态播报，不抢夺用户当前焦点。
+- 确认框关闭后将焦点返回调用按钮；完成后焦点保留在稳定区域，除非移动焦点能直接帮助修复错误。
+- 在紧凑宽度下允许命令换行、折叠筛选或进入溢出，但主任务不能变成仅右键或悬停可用。
+- 在浅色、深色、高对比度、100%–200% 缩放、长本地化文本和 Windows 贴靠宽度下验证；表格始终保留可用高度。
+
+## 13. 测试矩阵与交付检查清单
+
+### 测试矩阵
+
+至少验证：
+
+1. 学会第一个标签后，用户能否在其他标签找到数据来源、筛选、批量和完成命令；
+2. 各标签的命令名称、图标、顺序、主次层级和相同位置语义是否一致；
+3. 无文件、取消选择、格式无效、校验失败、重新导入、追加与替换；
+4. 无数据、筛选无结果、单选、多选、隐藏选择、刷新和数据冲突；
+5. 完成命令前置条件缺失、重复点击、快速完成、长任务、取消和迟到响应；
+6. 无需确认、覆盖文件、批量高影响、不可逆操作及确认取消后的焦点恢复；
+7. 明显成功、不可见成功、失败、部分成功、撤销和打开结果；
+8. 任务运行、存在脏状态或显示错误时切换/关闭标签和窗口；
+9. 紧凑、中等、宽、贴靠、最大化、100%–200% DPI、浅色、深色和高对比度；
+10. 纯键盘、屏幕阅读器、长文案和原型到最终桌面实现的契约对照。
+
+### 交付检查清单
+
+- [ ] 已证明标签模型适合任务，而不是用标签代替顶级导航。
+- [ ] 所有标签使用同一页面骨架和 Token，按语义省略不适用区域。
+- [ ] 每个命令的作用域、目标、前置条件、位置、风险、反馈和快捷入口明确。
+- [ ] 数据来源、表格视图、行、选择集和工作流完成命令没有混区。
+- [ ] “刷新”“更新”“生成”“提交”等名称准确区分读取与写入副作用。
+- [ ] 每个任务区域最多一个视觉主操作；危险操作与常规操作分离。
+- [ ] 导入状态、取消、校验、追加/替换、重新导入和错误恢复完整。
+- [ ] 底部完成区不遮挡表格，窄窗口下主操作仍可见。
+- [ ] 确认只用于不可逆、高成本、外部副作用或强制决策，不对普通操作滥用。
+- [ ] 普通成功不使用模态弹窗；结果不可见、失败和部分成功具有合适反馈与下一步。
+- [ ] 切换标签保留有价值的筛选、选择、滚动、脏状态和任务状态。
+- [ ] 原型与最终桌面实现使用同一页面、命令、确认和任务状态契约。

references/core-dialogs-tasks.md

@@ -0,0 +1,212 @@
+# 桌面对话框、反馈与长任务交互规范
+
+## 目录
+
+1. 选择反馈层级
+2. 对话框交互契约
+3. 焦点、按钮与关闭
+4. 确认、删除与未保存决策
+5. 进度、取消与后台任务
+6. 错误、重试与部分成功
+7. 通知、信息条与临时反馈
+8. 异步与生命周期
+9. 测试矩阵
+10. 交付检查清单
+
+## 1. 选择反馈层级
+
+使用能解决问题的最低干扰层级：
+
+| 场景 | 优先形式 | 不应使用 |
+|---|---|---|
+| 字段格式或局部操作错误 | 字段附近/组件内联反馈 | 应用级模态错误框 |
+| 页面加载失败、离线、权限或可恢复警告 | 页面内信息条/Banner，带操作 | 自动消失 Toast |
+| 简短、可忽略、无需立即操作的完成状态 | 非模态临时通知或状态区 | 阻塞对话框 |
+| 与当前对象相关的附加选择/详情 | Flyout/Popover/非模态面板 | 无原因的全窗口模态 |
+| 应用无法安全替用户决定 | 窗口级模态对话框 | 隐藏在状态栏的提示 |
+| 永久破坏贵重资产、安全/支付等高风险决策 | 明确后果的确认对话框 | 含糊“确定/取消” |
+| 长时间但可继续其他工作的任务 | 页面/任务中心进度，可后台化 | 锁住整个应用的旋转圈 |
+| 短暂阻塞且必须完成才能继续 | 局部遮罩或模态进度，支持取消时提供取消 | 假装确定进度的百分比 |
+
+同类、重复或持续状态应占据稳定界面位置，不要每次弹出。对常见可恢复操作优先直接完成并提供撤销，而不是反复确认。
+
+## 2. 对话框交互契约
+
+创建对话框前定义：
+
+- 为什么必须阻塞，以及阻塞当前窗口还是整个应用；
+- 标题、简短说明、影响对象和所需决策；
+- 主操作、次操作、取消/关闭、默认按钮与危险按钮；
+- 初始焦点、Tab 循环、Enter、Escape 和窗口关闭按钮行为；
+- 验证、提交中、失败、重试和成功后的关闭条件；
+- 所有者窗口、重复打开防护和对话框生命周期；
+- 屏幕阅读器名称、描述和状态播报。
+
+### 内容与动作
+
+- 标题直接说明决策，如“删除 3 个项目？”或“保存更改后关闭？”。
+- 正文说明不可见后果和影响范围，不重复标题或堆叠技术错误。
+- 按钮使用具体动词：“删除”“覆盖”“保存并关闭”，不要让危险操作叫“确定”。
+- 常用安全操作是视觉主按钮；不可恢复操作与其他按钮分离，并使用一致的危险样式。
+- 超过三项复杂选择通常应改成任务页面或向导，不把应用页面塞进对话框。
+- 对话框内只有完成决策所需内容；帮助和详细日志使用可展开区或外部入口。
+
+## 3. 焦点、按钮与关闭
+
+### 打开
+
+- 将焦点移入对话框。短对话框聚焦最安全且最可能的操作；复杂内容先聚焦标题/说明或第一个字段。
+- 不可逆决策默认聚焦取消或最安全操作，除非平台和业务有充分理由。
+- 记录调用者；关闭后将焦点返回调用者，调用者消失时返回逻辑后继。
+- 模态界面必须让背景在视觉和交互上都不可用；不能只添加 `aria-modal` 或半透明遮罩。
+
+### 操作
+
+- Tab/Shift+Tab 留在模态对话框内部；非模态面板允许按明确规则离开。
+- Enter 只触发当前有效的默认按钮；多行输入中默认换行。
+- Escape 执行取消/关闭，不提交或丢失输入；无法取消时解释原因并提供可见关闭路径。
+- 右上角关闭、Alt+F4、Escape 和取消按钮使用同一取消协议。
+- 提交中防重复操作；若可取消，取消请求与关闭 UI 是两个阶段，等待任务确认停止或忽略结果。
+
+### 关闭
+
+- 成功、取消、失败和窗口关闭返回可区分结果，调用方不能把所有关闭都当成功。
+- 验证失败或提交失败时保持对话框打开并保留输入。
+- 对话框关闭时清理订阅、计时器和任务回调，防止访问已销毁界面。
+- 避免同时打开多个相同对话框；重复请求应激活已有实例或排队。
+
+## 4. 确认、删除与未保存决策
+
+### 何时确认
+
+仅当操作不可逆、代价高、影响范围难以预见、涉及安全/支付，或应用无法安全提供撤销时确认。频繁删除草稿、移除可恢复项等优先立即执行并提供撤销。
+
+确认内容必须包含：动作、对象、数量、不可逆后果和必要条件。不要使用双重否定或“是否确定？”作为全部说明。
+
+### 未保存内容
+
+- 使用“保存 / 不保存 / 取消”而不是模糊的“是 / 否”。
+- 多文档退出列出受影响文档，并支持安全的“全部保存”与失败项处理。
+- 保存失败保持窗口/标签打开，提供重试、另存或恢复内容出口。
+- 不保存仅放弃明确列出的本地更改，不删除远程数据或其他自动保存版本。
+- 关闭、后退、切换账户和应用退出共享同一未保存协调器。
+
+### 覆盖与冲突
+
+- 文件或数据已变化时显示来源、时间和可理解差异，提供保留本地、重新加载、另存/复制或合并。
+- 默认操作选择数据损失最小的方案。
+- 不把版本冲突伪装成普通“保存失败”，也不要静默覆盖。
+
+## 5. 进度、取消与后台任务
+
+### 任务状态模型
+
+至少定义 `queued`、`running`、`pausing/paused`（适用时）、`cancelling`、`cancelled`、`succeeded`、`failed` 和 `partially-succeeded`。完成、失败与取消是终态，不能仅靠进度条是否消失判断。
+
+### 进度选择
+
+- 已知总量且进度可信时使用确定进度，显示完成量/总量或百分比及当前阶段。
+- 总量未知时使用不确定进度，并用具体文本说明正在做什么。
+- 先不确定、后可计算时允许切换为确定进度，但进度不能倒退或长期停在 99%。
+- 极短操作避免闪烁；稍长操作先显示局部忙碌状态，达到明显时长后升级为进度界面。
+- 后台任务显示在稳定任务中心/状态区，可重新找到；通知只作为补充。
+- 多文件/多阶段任务同时显示总体进度和当前项，不用每行一个永久旋转圈。
+
+### 取消
+
+- 只有任务真实支持安全取消时显示取消按钮。
+- 点击后进入 `cancelling`，禁用重复取消，并说明正在停止；不能立即谎称已取消。
+- 定义取消点、已完成工作的保留/回滚、临时文件清理和后端请求撤销。
+- 窗口关闭时明确任务取消、后台继续或转移到任务中心，不能让工作静默中断。
+- 取消后的迟到结果必须被请求 ID/任务状态拒绝，不能重新把 UI 改成成功。
+
+### 响应速度
+
+- 所有 I/O、计算和批处理离开 GUI 线程；通过线程安全消息更新进度。
+- 节流高频进度更新，避免每个字节/记录都刷新 UI。
+- 不使用 `processEvents()` 或嵌套事件循环掩盖阻塞。
+- 任务命令具有幂等/去重策略，双击按钮不能创建重复任务。
+
+## 6. 错误、重试与部分成功
+
+错误反馈回答：发生了什么、影响什么、用户能做什么、工作是否保留。
+
+### 错误分类
+
+- **用户可修复：** 指向字段、权限申请、文件位置或设置。
+- **暂时故障：** 提供重试、稍后处理、离线或切换服务。
+- **冲突：** 提供刷新、比较、合并、另存或放弃本地更改。
+- **不可恢复：** 保留诊断 ID/日志出口和安全返回路径，不暴露内部堆栈。
+
+### 重试
+
+- 重试只重复失败且安全的部分，保留已完成结果。
+- 不可幂等操作重试前查询实际状态或使用幂等键，避免重复付款、创建或删除。
+- 连续失败不无限弹窗；提供持久错误区和诊断入口。
+- 网络恢复自动重试时显示状态并限制退避；用户手动重试仍可用。
+
+### 部分成功
+
+- 显示成功、失败、跳过、取消的数量和对象范围。
+- 允许查看/导出失败详情、重试失败项或撤销成功项（可行时）。
+- 不用绿色“成功”覆盖失败项，也不因少量失败否认全部已完成工作。
+- 批量操作结束后刷新受影响数据，同时保持仍有效的选择和上下文。
+
+## 7. 通知、信息条与临时反馈
+
+### 信息条/Banner
+
+- 用于页面级可恢复问题、离线、权限、过期数据和需要操作的警告。
+- 保持到问题解决、用户关闭或上下文消失；关闭后是否再次出现由状态而非计时器决定。
+- 包含严重程度、简短文本、主要恢复动作和必要时的详情。
+- 出现时不抢焦点，但重要状态通过无障碍实时区域/平台事件播报。
+
+### 临时通知/Toast
+
+- 仅用于无需立即响应且不会因错过而阻塞任务的信息。
+- 不承载唯一的撤销入口、关键错误或复杂决策；重要历史可在任务/通知中心找到。
+- 避免连续堆叠相同通知，合并重复事件并限制频率。
+- 自动消失前给足阅读时间；键盘和屏幕阅读器用户能访问需要的操作。
+
+### 成功反馈
+
+- 页面内变化明显时无需额外“成功”弹窗。
+- 保存、复制、导出等结果不明显时提供简短状态，并包含位置或下一步。
+- 撤销反馈说明对象与时限；时限结束后命令状态一致，不留下失效按钮。
+
+## 8. 异步与生命周期
+
+- 每个对话框/任务有唯一实例或任务 ID、所有者和取消源。
+- 异步完成前核对窗口、页面和对象仍存在，且结果仍属于当前请求。
+- 关闭 UI 不等于工作已停止；分开管理可见状态和任务状态。
+- 应用挂起、退出、网络断开、凭据过期和权限变化时定义持久化/恢复。
+- 错误处理不能在后台线程直接操作 GUI；通过队列信号/调度器返回 UI 线程。
+- 记录必要诊断信息但过滤密码、令牌、个人数据和完整文件内容。
+- 任务完成通知不抢夺用户当前窗口或焦点；需要时提供“打开结果”。
+
+## 9. 测试矩阵
+
+至少验证：
+
+1. 内联、页面级、临时通知、Flyout 和模态层级选择是否正确；
+2. Enter、Escape、Alt+F4、关闭按钮、Tab 循环和焦点返回；
+3. 危险操作、可撤销删除、未保存和版本冲突；
+4. 确定/不确定进度、快速完成、长时间停顿和多阶段任务；
+5. 取消请求、取消中关闭、迟到成功、重复提交和应用退出；
+6. 网络失败、权限、超时、部分成功、重试失败和离线恢复；
+7. 多窗口所有者、父窗口关闭和重复打开同一对话框；
+8. 100%–200% 缩放、长文案、高对比度、减少动画、键盘和屏幕阅读器；
+9. 原型与最终桌面实现的按钮、结果、任务状态和错误恢复对照。
+
+## 10. 交付检查清单
+
+- [ ] 已使用最低干扰层级，不把所有反馈都放进对话框。
+- [ ] 对话框的阻塞范围、所有者、按钮、默认/取消和结果明确。
+- [ ] 焦点进入、循环、Escape、关闭和返回调用者符合平台行为。
+- [ ] 危险操作说明对象与后果，可恢复操作优先撤销。
+- [ ] 任务具有完整状态、可信进度、取消协议和重复提交防护。
+- [ ] 错误区分可修复、暂时故障、冲突和不可恢复，并保留用户工作。
+- [ ] 部分成功显示准确数量并支持失败项恢复。
+- [ ] 后台线程不操作 GUI，关闭后迟到回调安全忽略。
+- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
+- [ ] 原型与桌面实现使用同一决策和任务状态契约。

references/core-form-input.md

@@ -0,0 +1,186 @@
+# 桌面表单与输入交互规范
+
+## 目录
+
+1. 表单模式与交互契约
+2. 字段状态模型
+3. 控件选择与字段语义
+4. 验证时机与错误恢复
+5. 保存、取消与未保存状态
+6. 键盘、输入法与无障碍
+7. 异步、依赖字段与敏感数据
+8. 测试矩阵
+9. 交付检查清单
+
+## 1. 表单模式与交互契约
+
+设计前选择一种主提交模式，不要让同一表单中的字段随机采用不同规则：
+
+| 模式 | 适用场景 | 提交与失败行为 |
+|---|---|---|
+| 即时生效 | 可快速撤销的偏好、显示设置 | 值改变后提交；失败时恢复旧值或显示未应用状态 |
+| 显式提交 | 创建、编辑、支付、权限等成组数据 | 用户选择“保存/创建/应用”；失败时保留全部输入 |
+| 分步向导 | 内容多、存在顺序依赖或需分阶段确认 | 每步验证本步；返回不丢值；最终提交前汇总检查 |
+| 自动保存 | 长文档、草稿和持续编辑 | 显示保存中/已保存/失败/离线；保留本地可恢复副本 |
+
+在编码前定义：初始值来源、必填与可选、格式和领域约束、验证时机、提交范围、默认按钮、取消语义、脏状态、关闭策略、离线行为、权限和敏感字段处理。
+
+表单状态至少包括 `pristine`、`dirty`、`validating`、`valid`、`invalid`、`submitting`、`saved`、`save-failed` 和适用时的 `offline/conflict`。不要只维护一个 `isValid` 布尔值。
+
+## 2. 字段状态模型
+
+每个字段分别维护：
+
+- 原始值、编辑值和规范化后的提交值；
+- 是否访问、是否修改、是否正在组合输入、是否正在异步验证；
+- 本地格式错误、领域错误、服务端错误和警告；
+- 是否可编辑、只读、禁用、依赖项不可用或权限不足；
+- 最近一次有效验证所对应的值或请求 ID。
+
+### 状态规则
+
+- `disabled` 表示用户当前不能操作且通常不参与提交；`read-only` 表示值可读取、聚焦和复制但不可修改。不要互换。
+- 占位符不是标签，也不保存输入格式说明。标签、必填标记、帮助文本和错误信息各有独立位置。
+- 字段变脏后又恢复到原始规范值时清除脏状态，不能只比较显示字符串。
+- 外部数据刷新不得静默覆盖脏字段；显示冲突并让用户选择保留、重新加载或合并。
+- 控件被条件隐藏时明确其值是保留、清空还是不提交；不要留下不可见但生效的旧值。
+- 错误状态不能永久黏附在已修正值上，也不能因界面刷新而消失。
+
+## 3. 控件选择与字段语义
+
+| 数据意图 | 优先控件 | 关键规则 |
+|---|---|---|
+| 单行/多行自由文本 | 标准单行/多行文本控件 | 设置长度、换行、粘贴和空白规范 |
+| 密码或密钥 | 标准密码输入控件 | 默认遮蔽；不记录日志；明确显示/隐藏和复制策略 |
+| 有界整数/小数 | 标准数字输入控件 | 定义范围、步长、精度、单位、区域格式和空值 |
+| 二元立即设置 | 开关控件 | 标签表达状态或结果，不使用含糊的“开启” |
+| 独立布尔选择 | 复选框 | 定义未选、已选和确有语义时的不确定态 |
+| 少量互斥选项 | 单选按钮组 | 组名清晰；方向键切换；不要默认危险选项 |
+| 紧凑单选 | 下拉单选控件 | 区分自由输入与仅可选择；不要用作多选 |
+| 建议但允许自由输入 | 自动建议输入控件 | 区分输入文本、突出建议和已提交值 |
+| 日期/时间 | 平台日期时间控件 | 使用区域设置；明确时区、范围和是否允许空值 |
+| 文件/文件夹 | 平台选择器 | 显示最终路径/名称；处理取消、权限和不存在 |
+
+不要用自由文本复刻已有的日期、数字、枚举或文件选择控件。不要仅因视觉统一而移除平台输入法、撤销、剪贴板和辅助技术支持。
+
+## 4. 验证时机与错误恢复
+
+### 分层验证
+
+1. **输入约束：** 长度、字符集合和明显不可能的值；仅阻止真正无意义的输入。
+2. **字段验证：** 格式、范围、必填和单字段领域规则。
+3. **跨字段验证：** 开始/结束日期、密码确认、条件必填和互斥规则。
+4. **服务端验证：** 唯一性、权限、库存、版本冲突和最终业务规则。
+
+允许用户处于合理的中间输入状态，例如负号、小数点、未完成日期或输入法组合文本。不得在每次按键后强行格式化、移动光标或弹出错误。
+
+### 推荐时机
+
+- 输入前显示格式、单位、范围和示例等约束。
+- 首次失焦或提交时显示一般字段错误；字段已报错后可在修改时及时更新。
+- 跨字段规则在相关字段都可判断时验证，并把错误放在最能指导修复的位置。
+- 服务端验证使用防抖、取消或请求 ID；只应用与当前值匹配的最新结果。
+- 提交时重新运行所有适用规则；客户端验证不能替代服务端验证。
+
+### 错误呈现
+
+- 使用具体文案回答“哪里不对、为什么、怎样修复”，不要只写“输入无效”。
+- 错误紧邻字段并与字段建立无障碍关系；长表单在提交失败后提供错误摘要。
+- 聚焦第一个无效字段仅发生在用户提交后；输入过程中不要抢夺焦点。
+- 不只用颜色表达错误；保留输入、选择范围和滚动位置。
+- 网络失败与字段值无效是不同状态。网络失败提供重试或离线方案，不要把字段标红。
+- 警告允许继续时明确后果；错误阻止提交时明确所需修复。
+
+不要仅通过禁用提交按钮隐藏问题。若按钮禁用，附近要说明缺少什么；提交时仍必须验证，以覆盖键盘、程序调用和竞态。
+
+## 5. 保存、取消与未保存状态
+
+### 显式提交
+
+- 默认按钮使用具体动词，如“创建项目”“保存更改”，而不是泛化的“确定”。
+- 提交开始后防止重复请求，保留可阅读内容，并显示任务范围内的进度。
+- 成功后更新原始快照、清除脏状态并给出持久到足以感知的反馈。
+- 失败后保留输入；将字段错误映射到字段，将全局错误放在表单级反馈区。
+- 服务端只接受部分字段时明确成功与失败，不要假装整体保存成功。
+
+### 取消与关闭
+
+- “取消”撤销本次未提交编辑并返回稳定位置；不应撤销提交前已明确即时生效的其他设置。
+- 无修改时直接关闭。有未保存修改时优先自动保存草稿或提供“保存 / 不保存 / 取消关闭”。
+- 不可恢复且代价高的更改才要求确认；频繁、可恢复的小修改优先撤销。
+- 关闭确认必须基于领域脏状态，而不是仅监听是否发生过按键。
+- 应用退出、标签关闭、页面导航和窗口关闭使用同一未保存策略。
+
+### 即时生效与自动保存
+
+- 乐观更新失败时恢复旧值或把字段标为未同步；不得显示已应用但实际未保存。
+- 连续变化使用合并、防抖或串行队列，保证旧响应不能覆盖新值。
+- 自动保存显示最近保存状态；离线时保留本地草稿并说明同步状态。
+- 取消自动保存任务时不得删除最后一个已确认版本。
+
+## 6. 键盘、输入法与无障碍
+
+- Tab/Shift+Tab 按视觉和任务顺序移动；复合控件内部使用平台标准方向键。
+- Enter 在单行字段中执行明确的默认提交，在多行编辑器中默认换行；需要 Ctrl+Enter 提交时显示提示。
+- Escape 关闭建议、日期弹层或临时模式；不得无提示清空整份表单。
+- 使用访问键和标准快捷键；不要覆盖输入法、屏幕阅读器或文本编辑快捷键。
+- 标签与字段、帮助与描述、错误与字段建立程序化关系；必填和无效状态可被屏幕阅读器感知。
+- 单选组、复选组和相关字段具有组名；错误摘要中的项目可将焦点移到对应字段。
+- 在 200% 文本/显示缩放、中文输入法、屏幕键盘和高对比度下验证。
+
+### 输入法组合
+
+中文、日文、韩文等输入法组合期间，不执行最终格式化、远程搜索、自动提交或破坏性的字段重写。组合完成后再触发需要完整文本的验证。粘贴、撤销、重做、语音输入和自动填充必须经过同一规范化与验证流程。
+
+不要在用户输入过程中反复替换整个字符串。格式化数字、电话或证件号时保持光标、选择范围和输入法状态，并允许复制未经装饰的领域值。
+
+## 7. 异步、依赖字段与敏感数据
+
+### 异步验证
+
+- 为每次请求关联字段值、记录版本和请求 ID；只接受仍匹配当前编辑值的结果。
+- 显示 `validating`，但避免阻止用户继续填写无关字段。
+- 提交与验证竞态时等待最新必要验证或在服务端统一裁决。
+- 取消窗口或离开页面时取消请求或忽略回调，不能访问已销毁 UI。
+- 缓存结果时包含影响有效性的上下文，如租户、权限和相关字段。
+
+### 依赖字段
+
+- 父字段变化导致子选项失效时，明确清空、重新选择或保留不可用值。
+- 加载子选项时保持标签和布局稳定，显示加载/失败/重试。
+- 条件必填规则同步更新标签、帮助、验证和无障碍状态。
+- 自动计算字段默认只读；允许覆盖时明确“自动/手动”来源和恢复方式。
+
+### 敏感数据
+
+- 不把密码、令牌、支付数据或个人信息写入日志、URL、分析事件和普通崩溃上下文。
+- 明确剪贴板、显示/隐藏、超时清除和截屏风险；不要默认禁止所有粘贴或密码管理器。
+- 错误消息不泄露账户是否存在、权限细节或服务端内部信息。
+- HTML 原型只使用虚构数据，不模拟采集真实敏感信息。
+
+## 8. 测试矩阵
+
+至少验证：
+
+1. 初始、修改、恢复原值、只读、禁用、条件隐藏和权限变化；
+2. 空值、边界值、超长值、空白、非法字符、区域数字、日期和时区；
+3. 首次失焦、重复编辑、提交失败、修复后重提和服务器字段错误；
+4. 中文输入法组合、粘贴、撤销/重做、自动填充和屏幕键盘；
+5. 异步验证乱序、取消、超时、离线和字段依赖变化；
+6. 双击提交、连续即时更新和旧响应覆盖新值；
+7. 页面导航、标签关闭、窗口关闭和应用退出时的未保存决策；
+8. 100%–200% 缩放、窄窗口、长翻译、高对比度、键盘和屏幕阅读器；
+9. 原型与最终桌面实现的字段、规则、错误和提交状态对照。
+
+## 9. 交付检查清单
+
+- [ ] 已选择即时生效、显式提交、分步或自动保存模式。
+- [ ] 每个字段的原始值、编辑值、脏状态和验证状态明确。
+- [ ] 控件与数据类型匹配，标签、帮助、必填和错误语义完整。
+- [ ] 允许合理中间输入和输入法组合，不在每次按键后破坏文本。
+- [ ] 本地、跨字段和服务端验证时机及错误位置明确。
+- [ ] 保存失败保留输入，取消和关闭使用统一未保存策略。
+- [ ] 异步请求具有取消/过期保护，旧响应不能覆盖新值。
+- [ ] 敏感信息不进入日志、URL、原型真实数据或普通分析事件。
+- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
+- [ ] 原型与桌面实现使用同一字段和状态契约。

references/core-html-prototype.md

@@ -1,4 +1,4 @@
-# HTML 原型评审与桌面实现交接
+# 桌面 HTML 原型评审与实现交接
 
 ## 目录
 
@@ -7,7 +7,7 @@
 3. 原型技术与目录约束
 4. 必须覆盖的内容与状态
 5. 客户评审与验收边界
-6. 从 HTML 交接到 WinUI 或 Qt
+6. 从 HTML 交接到目标桌面适配器
 7. 变更管理与完成标准
 8. 常见反模式
 
@@ -20,7 +20,7 @@ HTML 原型用于低成本验证信息架构、内容层级、视觉 Token、窗
 - 新产品、主要窗口、关键业务流程或显著视觉改版；
 - 客户需要在原生开发前确认范围、流程或视觉；
 - 多角色、多状态或跨页面交互仅靠静态图难以说明；
-- WinUI、PySide/PyQt 团队需要统一实现基准。
+- 多种桌面框架团队需要统一实现基准。
 
 仅修正文案、颜色、间距或单个明确控件时，可以说明理由后跳过。跳过不等于省略状态、无障碍和验收要求。
 
@@ -81,23 +81,32 @@ HTML 原型用于低成本验证信息架构、内容层级、视觉 Token、窗
 必须声明以下内容不能仅靠 HTML 验收：
 
 - 原生标题栏、系统菜单、Snap Layouts、多窗口和任务栏行为；
-- WinUI/Qt 控件的精确尺寸、字体栅格化和系统主题差异；
+- 原生控件的精确尺寸、字体栅格化和系统主题差异；
 - Mica/Acrylic、原生弹出层、输入法和多显示器 DPI 行为；
-- Narrator/UI Automation/Qt Accessibility 的最终语义；
+- 屏幕阅读器和目标框架无障碍 API 的最终语义；
 - 启动速度、内存、虚拟化、线程、打包、升级和生产数据性能。
 
 验收记录至少包含原型版本或提交、日期、审批人、确认项、遗留项和明确排除项。未回复不能自动视为确认。
 
-## 6. 从 HTML 交接到 WinUI 或 Qt
+## 6. 从 HTML 交接到目标桌面适配器
 
 确认后冻结原型版本，并建立追踪表：
 
-| 原型项 | 设计 Token/状态 | WinUI 实现 | Qt Widgets/QML 实现 | 差异与验证 |
-|---|---|---|---|---|
-| 导航 | 层级、选中、折叠 | `NavigationView` 等 | `QListView` + 页面容器等 | 键盘、窗口断点 |
-| 共享命令 | 文本、图标、启用状态 | `XamlUICommand`/命令 | `QAction` | 快捷键、上下文 |
-| 数据集合 | 空、加载、选择、分页 | 虚拟化集合控件 | Model/View | 大数据性能 |
-| 对话与反馈 | 模态性、默认操作 | `ContentDialog`/信息条 | `QDialog`/语义 Banner | 焦点、Escape |
+| 原型项 | 设计 Token/状态 | 目标框架意图 | 适配器验证 |
+|---|---|---|---|
+| 导航 | 层级、选中、折叠 | 平台导航、标签或页面容器 | 键盘、窗口断点、状态恢复 |
+| 共享命令 | 文本、图标、启用状态 | 可复用命令对象或集中 action | 快捷键、上下文和权限 |
+| 数据集合 | 空、加载、选择、分页 | 虚拟化列表/表格与稳定数据模型 | 大数据性能和选择保持 |
+| 对话与反馈 | 模态性、默认操作 | 平台对话框、页面信息条和任务反馈 | 焦点、Escape、所有者和生命周期 |
+
+原型中的组件语义保持集中：
+
+- 表单优先使用原生 `form`、`label`、`input`、`select`、`textarea` 和 `button`，模拟字段、异步和提交错误。
+- 静态数据优先使用 `<table>`；只有实现完整二维键盘模型时才使用交互式 `grid` 语义。
+- 标签使用 `tablist`、`tab`、`tabpanel` 关系，隐藏面板不得保留可聚焦子元素。
+- 模态界面优先使用原生 `<dialog>` 或经验证实现，并管理背景 inert、焦点循环、Escape 和焦点返回。
+- 使用稳定 ID 和事件委托区分单击、双击、上下文菜单及单元格内控件；不要依赖 DOM 索引作为业务身份。
+- 使用可访问状态文本或实时区域模拟进度、错误和部分成功，但不抢夺焦点或重复播报。
 
 交接时遵循以下规则：
 
@@ -119,7 +128,7 @@ HTML 原型阶段完成必须同时满足：
 - 不含真实凭据和生产副作用；
 - 客户能按说明独立运行；
 - 已形成书面确认、遗留项和排除项；
-- 已建立到 WinUI 或 Qt 的控件与状态映射。
+- 已建立到所选桌面适配器的控件与状态映射。
 
 ## 8. 常见反模式
 

references/core-navigation-tabs.md

@@ -0,0 +1,178 @@
+# 桌面导航、标签页与窗口交互规范
+
+## 目录
+
+1. 选择导航模型
+2. 目的地、路由与状态模型
+3. 导航、后退与焦点恢复
+4. 自适应导航与应用外壳
+5. 静态标签与文档标签
+6. 未保存内容与关闭协议
+7. 多窗口与窗口生命周期
+8. 键盘与无障碍
+9. 测试矩阵
+10. 交付检查清单
+
+## 1. 选择导航模型
+
+先根据用户心智模型选择，不按视觉偏好混用：
+
+| 模型 | 表达含义 | 典型呈现 |
+|---|---|---|
+| 顶级导航 | 在应用主要目的地之间切换 | 带标签的侧边或顶部导航 + 页面容器 |
+| 层级导航 | 进入对象或任务的下一级，并允许后退 | 路由栈、主从页面或显式导航控制器 |
+| 静态标签 | 在少量、固定、同一对象的同级属性页之间切换 | 不可关闭的标签或分段选择器 |
+| 文档标签 | 管理可创建、关闭、重排和可能移动到窗口的工作文档 | 可关闭、移动和溢出的文档标签 |
+| 多窗口 | 并行展示独立任务、文档或工具 | 具有独立状态容器的顶层窗口 |
+| 辅助面板 | 补充当前任务，不成为新的顶级目的地 | 侧面板、检查器或可停靠面板 |
+
+不要使用标签页表示彼此无关的应用目的地，也不要用顶级导航伪装可关闭文档。层级导航、文档历史和编辑撤销是三种独立历史，不共用一个“后退”命令。
+
+在编码前定义：目的地清单、稳定 ID、层级关系、可深链参数、进入/离开条件、后退语义、状态保留、加载策略、权限、未保存行为、多窗口所有权和恢复策略。
+
+## 2. 目的地、路由与状态模型
+
+### 稳定身份
+
+- 使用路由/目的地 ID、文档 ID 和窗口 ID 标识状态，不使用导航项索引或当前标签位置。
+- 路由参数只包含可序列化的最小身份；大型对象和敏感数据放在应用状态/服务中。
+- 同一文档重复打开时明确激活现有标签、创建只读副本，还是允许多个编辑会话。
+- 权限变化或对象删除后，历史记录不得导航到可操作的幽灵页面；显示可恢复状态或移除记录。
+
+### 每个页面保存什么
+
+按产品价值决定保留：滚动位置、选中对象、筛选、展开节点、输入草稿、焦点目标、分页和子视图。持久业务数据与临时视图状态分开。
+
+- 前进/后退通常恢复页面上下文，不重新创建空白页面。
+- 刷新数据不应默认清空用户位置；无法恢复时将焦点放到语义最近的位置。
+- 导航缓存需要容量和失效策略，不能无限保留页面、订阅、线程和敏感数据。
+- 恢复失败时安全回到有效目的地并说明原因，不崩溃或显示空壳。
+
+## 3. 导航、后退与焦点恢复
+
+### 进入目的地
+
+- 点击当前已激活的顶级导航项默认不重复压栈；需要“回到顶部/刷新”时显式定义。
+- 导航启动后防止重复触发。异步加载显示当前目的地的骨架/进度，并忽略过期结果。
+- 先确认离开条件，再切换选中导航项；被未保存状态阻止时恢复原导航视觉。
+- 失败时保留上一页或显示可操作错误，不短暂显示目标页后再弹回。
+
+### 后退与前进
+
+- 仅在有有效历史时启用后退；不要显示一个永远禁用的装饰按钮。
+- `Alt+Left`/鼠标后退键按应用导航历史返回；不要撤销编辑或关闭文档。
+- 后退前运行与直接导航相同的未保存协调器。
+- 从详情返回列表时恢复筛选、选择、滚动和焦点；目标已删除时选择相邻项或列表容器。
+- 深链首次进入没有应用内上一页时，后退回到合理的应用起点或关闭该任务窗口，规则必须明确。
+
+### 焦点
+
+- 导航完成后把焦点放到页面标题、主内容或恢复的任务位置，而不是留在不可见导航项。
+- 用户通过键盘选择导航项时保持可预测焦点；指针导航不应无必要抢走当前输入焦点。
+- 弹层、对话框和辅助面板关闭后将焦点返回调用者或逻辑后继。
+- 加载完成不自动把焦点从用户正在操作的其他控件抢走。
+
+## 4. 自适应导航与应用外壳
+
+- 紧凑、中等、宽布局使用同一目的地和选择状态，只改变呈现方式。
+- 导航面板折叠/展开不重建页面、不清空历史、不丢焦点。
+- 紧凑模式保留可发现的打开导航入口；图标必须有文本/工具提示和无障碍名称。
+- 顶级项保持稳定顺序。权限或功能开关改变时，移除无权项并处理当前目的地回退。
+- 标题栏拖动区域不能覆盖导航按钮、搜索、标签关闭或窗口命令。
+- 设置、账户和帮助等固定项与主要业务目的地分组，但仍参与明确的焦点顺序。
+- 窗口变窄时优先折叠次要面板、重排主从内容，再隐藏低频命令；不把关键任务变成仅菜单可用。
+
+## 5. 静态标签与文档标签
+
+### 静态标签
+
+- 用于少量固定同级页面，不提供新建、关闭、拖动或未保存标记。
+- 标签切换应快速。内容加载有明显延迟时使用手动激活：方向键移动焦点，Enter/Space 激活。
+- 标签名称简短且稳定；不要用仅图标标签承载关键分类。
+- 切换后保留每页内部状态，除非数据刷新是明确操作。
+
+### 文档标签
+
+每个文档标签维护稳定文档 ID、标题、脏状态、加载/错误、只读/冲突、固定状态和所属窗口。标签位置只是显示顺序。
+
+- 单击激活文档；关闭按钮只关闭命中标签，不先意外切换并触发其他副作用。
+- 支持关闭当前、关闭其他、关闭右侧等命令时准确处理固定标签和未保存标签。
+- 关闭后优先激活最近使用或邻近标签，并将焦点放到合理位置。
+- 重排不改变文档身份、保存目标、撤销栈或后台任务所有权。
+- 标签太多时提供滚动、溢出列表或搜索；不能把标签压缩到无法识别。
+- 标签标题变化保持关闭按钮位置稳定；脏状态使用符号并提供无障碍文本，不只变颜色。
+- 双击标签、双击空白区和中键关闭仅作为加速路径，必须有显式按钮/菜单/键盘入口。
+- 拖出新窗口是高级能力；需定义取消拖动、跨 DPI、失败回退和最后标签行为。
+
+### 标签键盘
+
+- Ctrl+Tab/Ctrl+Shift+Tab 在文档标签间切换；是否按显示顺序或最近使用顺序要保持一致。
+- Ctrl+W 关闭当前可关闭文档；不会绕过未保存检查。
+- 标签条聚焦后使用方向键移动，Enter/Space 激活；Delete 关闭仅在产品明确采用时启用。
+- 关闭后焦点移动到新激活标签或逻辑后继，不落到已删除对象。
+
+## 6. 未保存内容与关闭协议
+
+所有离开路径调用同一关闭协调器：导航离开、后退、关闭标签、关闭窗口、退出应用、切换账户和外部打开另一文档。
+
+推荐协议：
+
+1. 收集受影响的脏文档/表单和正在提交的任务；
+2. 无修改则直接继续；可自动保存则先安全保存；
+3. 需要决策时显示具体对象和“保存 / 不保存 / 取消”；
+4. 多文档退出支持逐项或“全部保存”，并报告失败项；
+5. 只有全部必要保存成功或用户明确放弃后才完成关闭；
+6. 取消关闭恢复原窗口、标签、导航选择和焦点。
+
+- 保存失败不得关闭；保留内容并提供重试、另存或复制恢复数据。
+- 后台任务与文档绑定时定义关闭后取消、继续后台或转移所有权。
+- 进程崩溃恢复与正常未保存提示分开；恢复草稿不能覆盖较新的服务端版本。
+- 不用“是否发生过键盘输入”判断脏状态，应比较规范化领域快照或命令状态。
+
+## 7. 多窗口与窗口生命周期
+
+- 每个窗口具有明确任务、所有者和状态容器；不要依赖全局“当前窗口”。
+- 应用级服务可以共享，页面选择、导航历史、焦点、文档视图状态通常按窗口隔离。
+- 辅助窗口定义模态性、任务栏显示、始终置顶、最小化/恢复和父窗口关闭行为。
+- 同一文档在多窗口编辑时定义单写者、协同、只读副本或冲突策略。
+- 关闭父窗口前处理其拥有的对话框、弹层、未保存内容和后台任务。
+- 保存窗口位置/尺寸/最大化/停靠布局；恢复时限制到当前显示器可用区域。
+- 显示器移除、DPI 改变或窗口恢复失败时使用安全默认位置和最小可用尺寸。
+- 最后一个窗口关闭是退出、留在托盘还是保留后台服务必须明确，不让任务静默终止。
+
+## 8. 键盘与无障碍
+
+- 顶级导航、标签条和页面内容是不同复合区域；Tab 在区域间移动，方向键在区域内移动。
+- 当前导航目的地与键盘焦点分别可见，并向无障碍 API 暴露选中/激活状态。
+- 后退、关闭、新建标签、切换标签和窗口命令具有标准快捷键及菜单说明。
+- 标签关闭按钮、仅图标导航项和窗口按钮提供准确名称；重复标签增加可区分上下文。
+- 页面标题使用可导航语义；导航完成和错误加载时播报目的地变化，但不重复朗读整页。
+- 高对比度、200% 缩放和长翻译下仍能识别活动目的地、活动标签、脏状态和关闭入口。
+- 动效尊重系统减少动画设置；转场不延迟输入或导致前庭不适。
+
+## 9. 测试矩阵
+
+至少验证：
+
+1. 当前目的地重复点击、快速连续导航、加载失败和过期响应；
+2. 后退/前进、深链首次进入、对象删除和权限变化；
+3. 紧凑/宽导航切换、贴靠、标题栏命中和焦点保持；
+4. 静态标签、文档新建/关闭/重排/溢出和重复打开；
+5. 单个/多个脏文档的保存、不保存、取消和保存失败；
+6. Ctrl+Tab、Ctrl+W、Alt+Left、方向键、Enter、Space、Delete 和 Shift+F10；
+7. 多窗口共享文档、关闭父窗口、最后窗口和后台任务；
+8. 窗口位置恢复、显示器移除、100%–200% DPI 和高对比度；
+9. 屏幕阅读器对目的地、活动标签、脏状态、标签数量和加载结果的播报；
+10. 原型与最终桌面实现的路由、关闭和恢复契约对照。
+
+## 10. 交付检查清单
+
+- [ ] 已区分顶级导航、层级导航、静态标签、文档标签和多窗口。
+- [ ] 所有目的地、文档和窗口使用稳定 ID，不依赖显示索引。
+- [ ] 后退、刷新和导航失败能够保留或安全恢复用户上下文。
+- [ ] 标签关闭、重排、溢出、快捷键和焦点后继明确。
+- [ ] 所有离开路径共享未保存协调器，保存失败不会丢失内容。
+- [ ] 多窗口的所有权、共享状态、关闭和最后窗口行为明确。
+- [ ] 自适应布局不会重建状态或破坏标题栏命中。
+- [ ] 键盘、缩放、高对比度和屏幕阅读器已验证。
+- [ ] 原型与桌面实现使用同一路由和文档状态契约。

references/engineering-validation.md

@@ -1,143 +0,0 @@
-# WinUI 工程实现与验证
-
-## 目录
-
-1. 版本与依赖门槛
-2. XAML 与状态架构
-3. 窗口化与响应式实现
-4. 性能与异步行为
-5. 实现评审
-6. 发布测试矩阵
-7. 严重程度模型
-8. 官方资料
-
-## 1. 版本与依赖门槛
-
-生成 XAML 或 C# 前：
-
-1. 阅读项目文件、中央软件包属性、目标框架、目标/最低 Windows 版本和已安装软件包。
-2. 准确确定 Windows App SDK 和 Windows Community Toolkit 版本。
-3. 检查项目是已打包还是未打包，以及是否使用单项目 MSIX。
-4. 在当前 Microsoft 文档中验证建议的 API；对于控件，还要在 WinUI 3 Gallery 中验证。
-5. 在建议中记录最低版本和回退行为。
-
-WinUI 3 使用 `Microsoft.UI.Xaml`。将使用 `Windows.UI.Xaml`、WinUI 2 Gallery 或 UWP 特有 API 的示例视为迁移参考，而不是可直接复制的代码。
-
-版本敏感指南示例：
-
-- WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本；
-- `SystemBackdropElement` 需要 Windows App SDK 1.6.3 或更高版本；
-- Mica 需要 Windows 11，在 Windows 10 回退为纯色主题表面；
-- Windows Community Toolkit `DataGrid` 已归档，并非 WCT 8+ 的 WinUI 3 控件。
-
-对于任何第三方控件，记录软件包、版本、许可证、维护状态、支持的 Windows 版本、主题/高对比度行为、UI Automation 支持、键盘模型、本地化、虚拟化和退出方案。
-
-## 2. XAML 与状态架构
-
-- 遵循项目现有的 MVVM 或代码隐藏约定；不要为一个界面引入第二套架构。
-- 当同一操作出现在按钮、菜单、上下文菜单和快捷键中时，将用户操作表示为可复用命令。
-- 根据场景明确表示视图状态：空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限被拒绝和部分结果。
-- 在资源字典中集中管理语义颜色、文本样式、间距、几何、图标大小和动效。
-- 需要在应用运行时变化的值使用 `ThemeResource`；仅当不需要运行时主题更新时使用 `StaticResource`。
-- 需要自定义 Token 时，在主题字典中放置浅色、深色和高对比度映射。
-- 优先使用样式和组合，不要复制完整控件模板。自定义模板将承担所有视觉和无障碍状态的实现责任。
-- 一致使用 `x:Bind` 或项目既有的绑定方式。为可编辑值明确绑定模式和更新时间。
-- 结构化布局使用 Grid 和弹性尺寸；避免深层嵌套面板，以及会破坏本地化或文本缩放的固定尺寸。
-- 让视觉顺序与阅读和 Tab 顺序一致。
-
-不要用 UI 线程调度掩盖不合理的异步所有权。只封送真正需要 UI 线程的最终状态更新，并确保视图仍然存在。
-
-## 3. 窗口化与响应式实现
-
-### 标题栏
-
-保留系统标题按钮和系统菜单。沿应用画布顶部定义拖动区域，将交互式子元素排除在拖动区域外，并测试活动/非活动外观。验证最大化、还原、调整大小、Snap Layouts、触控、右键系统菜单和高对比度。
-
-项目版本支持时，优先使用平台 `TitleBar` 控件。与 `NavigationView` 一起使用时，让一个组件负责后退和窗格切换行为，不要显示重复按钮。
-
-### 响应式布局
-
-从安全的紧凑布局开始，再添加较宽的视觉状态。使用有效窗口/内容宽度。双向测试每个转换并保留：
-
-- 选择和键盘焦点；
-- 滚动位置和展开状态；
-- 输入和验证状态；
-- 命令可用性；
-- 无障碍阅读顺序。
-
-如果重排或重新定位已足够，不要在每次调整大小时替换整个可视化树。对昂贵的大小调整工作进行防抖，不要只因为窗口跨越断点就重建数据集合。
-
-### 多窗口
-
-定义所有权、激活、持久化位置、最小尺寸、关闭确认和共享数据生命周期。确保命令作用于活动文档/窗口上下文，并让对话框具有正确的 XamlRoot/所有者。
-
-## 4. 性能与异步行为
-
-- 保持集合虚拟化，并使用真实数据、图像、模板和分组进行测量。
-- 在底层自定义 `ItemsRepeater` 前，优先使用 `ListView`、`GridView` 或 `ItemsView` 的行为。
-- 按接近渲染尺寸解码图像，避免为缩略图加载全分辨率资源，并取消已回收项目的工作。
-- 避免在 UI 线程上执行同步文件、网络、数据库或昂贵的序列化工作。
-- 让异步命令具备幂等性，或在工作进行时阻止重复调用。
-- 支持取消长时间操作；导航、搜索查询变化或窗口关闭后忽略过期结果。
-- 立即提供命令反馈。对接近瞬时完成的工作，可轻微延迟大型骨架屏/进度过渡以避免闪烁，但绝不能让 UI 看起来冻结。
-- 安全时在刷新期间保留之前可用的内容；区分刷新和首次加载。
-- 尽可能为不透明度和变换设置动画；避免对大型可视化树使用引发布局的动画。
-- 将昂贵的次要内容延迟到请求时加载，但没有明确方案时，不要延迟加载键盘顺序或核心任务理解所需的控件。
-- 测量启动、导航、调整大小、输入延迟、滚动流畅度、内存增长，以及设备/主题变化后的恢复。
-
-## 5. 实现评审
-
-先检查正确性，再评审视觉润色：
-
-- [ ] 命名空间、API、软件包版本和最低操作系统有效。
-- [ ] 项目能够构建，且未在修改范围内引入警告。
-- [ ] 命令不会重复提交，失败时保留用户工作。
-- [ ] 每个数据界面根据需要具有加载、空、错误和重试行为。
-- [ ] 虚拟化、回收和取消能处理生产规模数据。
-- [ ] 主题资源在运行时更新，自定义 Token 覆盖高对比度。
-- [ ] 布局能够承受紧凑宽度、长字符串、文本缩放和显示缩放。
-- [ ] 焦点、选择、无障碍名称、角色、状态和播报正确。
-- [ ] 标题按钮、拖动区域、对话框和多窗口所有权行为正确。
-- [ ] 破坏性操作使用与后果成比例的撤销或确认。
-
-## 6. 发布测试矩阵
-
-测试代表性组合，而不是只测试一台理想机器：
-
-| 维度 | 最低覆盖范围 |
-|---|---|
-| Windows | 最低支持的操作系统和当前 Windows 11 |
-| 窗口 | 支持的最小尺寸、小 `<=640` epx、中 `641–1007`、大 `>=1008`、贴靠、最大化 |
-| 缩放 | 常见的 100%、125%、150%、200% 显示缩放和显示器切换 |
-| 文本 | 默认和增大的 Windows 文本大小 |
-| 主题 | 浅色、深色、高对比度；透明效果开启和关闭 |
-| 输入 | 仅键盘、鼠标，以及产品声明支持时的触控/笔 |
-| 辅助技术 | Narrator、放大镜、Accessibility Insights/Inspect |
-| 内容 | 空、单项、真实数据、超大数据、长本地化字符串、失败 |
-| 环境 | 慢速存储/网络、离线、权限被拒绝、相关时的 RDP 或材质回退 |
-| 生命周期 | 适用时的挂起/关闭、重新打开、升级、辅助窗口关闭、崩溃安全的数据恢复 |
-
-自动执行稳定检查，但为 Narrator 流程、焦点可见性、触控舒适度、动效、文案、层级和感知响应速度保留人工评审。
-
-## 7. 严重程度模型
-
-评审设计或实现时使用以下顺序：
-
-| 严重程度 | 定义 | 示例 |
-|---|---|---|
-| 阻断 | 阻止主要任务、排除某种输入/无障碍方式、丢失数据或使用不可用 API | 键盘陷阱、保存按钮被裁切、假设已归档控件仍存在 |
-| 严重 | 导致频繁错误、迷失方向、内容不可访问，或严重的响应式/性能问题 | 焦点返回错误、大型列表未虚拟化、深色模式不可读 |
-| 中等 | 降低任务效率，或产生虽有替代方案但不一致的 Windows 行为 | 隐藏上下文命令、空状态薄弱、选择行为不一致 |
-| 轻微 | 对任务影响很小的润色问题 | 间距偏差、图标字重不一致、不必要的阴影 |
-
-每项发现都要指出界面/控件、触发条件、用户影响和最小稳健修正方案。避免“让它更现代”等模糊反馈。
-
-## 8. 官方资料
-
-- [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
-- [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
-- [NavigationView 标题栏集成](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
-- [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
-- [ListView 与 GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
-- [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
-- [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)

references/windows-foundations.md

@@ -37,7 +37,7 @@
 - `space.1` 到 `space.n`、`radius.control`、`radius.overlay`；
 - `motion.fast`、`motion.normal` 和共享缓动 Token。
 
-在有对应资源时，将这些语义映射到 WinUI 主题资源。让品牌 Token 位于平台 Token 之上，明确浅色、深色和高对比度映射。
+在目标框架有对应能力时，将这些语义映射到主题、调色板或样式资源。让品牌 Token 位于 Windows 平台 Token 之上，明确浅色、深色和高对比度映射。
 
 每个局部任务区域只使用一个主要强调操作。先通过尺寸、间距、对齐和字重建立层级，再增加颜色或表面。
 
@@ -75,29 +75,29 @@
 - 不要只通过降低不透明度表达状态。保持文本、焦点、选择和禁用语义可辨认。
 - 不要把关键文本放在无法确定可读性的材质或图像上，必须提供明确可读的回退方案。
 
-优先使用文本填充、控件填充、描边、强调色填充和系统状态画刷等系统资源。生成代码前，根据项目的 Windows App SDK 版本验证资源名称。
+优先使用文本填充、控件填充、描边、强调色填充和系统状态画刷等系统资源。生成代码前，根据目标框架、版本和平台能力验证资源名称。
 
 ## 5. 材质与层级
 
 使用材质来明确层级，不要装饰每个容器：
 
-| 需求 | 首选机制 | 说明 |
+| 需求 | 首选材质 | 说明 |
 |---|---|---|
-| 主窗口背景 | `MicaBackdrop` | 用于 Windows 11；在 Windows 10 回退为纯色 |
-| 可透视桌面的窗口 | `DesktopAcrylicBackdrop` | 视觉更活跃；仅在体验确有收益时使用 |
-| 特定区域的材质 | `SystemBackdropElement` | 需要 Windows App SDK 1.6.3 或更高版本 |
-| 模糊窗口内部内容 | 应用内 `AcrylicBrush` | 不会显示应用背后的桌面 |
+| 主窗口背景 | Mica | 用于 Windows 11；在 Windows 10 或框架不支持时回退为纯色 |
+| 可透视桌面的窗口 | Desktop Acrylic | 视觉更活跃；仅在体验确有收益且框架安全支持时使用 |
+| 临时菜单和浮层 | Acrylic 或主题浮层色 | 用于表达临时层级，并准备不透明回退 |
+| 模糊窗口内部内容 | 应用内模糊材质 | 不应误导用户以为能透视应用后的桌面 |
 | 简单内容表面 | 主题纯色 | 通常是最清晰且成本最低的选择 |
 
-不要在 WinUI 3 中使用 UWP `HostBackdrop` 模式。透明效果关闭、硬件不足、节电模式抑制 Acrylic、使用远程桌面或启用高对比度时，允许系统自动回退。确保回退颜色仍能维持层级和对比度。
+透明效果关闭、硬件不足、节电模式抑制 Acrylic、使用远程桌面或启用高对比度时，允许系统或适配器回退。确保回退颜色仍能维持层级和对比度；具体 API、版本门槛和禁用条件由所选框架适配文档定义。
 
 仅用层级表达重叠、焦点或临时 UI。优先使用系统阴影和覆盖层行为。不要仅为了让卡片显得凸起而引入外部阴影控件。
 
 ## 6. 字体、图标与动效
 
-默认使用 Segoe UI Variable 和 WinUI 字体层级。复用平台文本样式，不要在整个 XAML 中重复数值字号。正文使用常规字重，标题或标签使用更强字重，对齐的数字数据使用等宽数字，并优先换行而不是截断。无法避免截断时，通过无障碍工具提示或详情界面公开完整值。
+Windows 11 优先使用 Segoe UI Variable；不具备该字体或平台映射时回退到 Segoe UI 或目标框架的 Windows 系统字体。复用平台文本层级，不要在各页面重复数值字号。正文使用常规字重，标题或标签使用更强字重，对齐的数字数据使用等宽数字，并优先换行而不是截断。无法避免截断时，通过无障碍工具提示或详情界面公开完整值。
 
-使用 `SymbolIcon`、搭配 Segoe Fluent Icons 的 `FontIcon`，或一致的矢量资源集。保持图标隐喻、大小、描边/填充风格和对齐一致。为不熟悉或仅有图标的命令提供无障碍名称和工具提示。不要使用 Emoji 作为导航或命令图标。
+使用 Segoe Fluent Icons 能力或一致、授权明确的矢量资源集；目标系统缺少字体字形时必须回退。保持图标隐喻、大小、描边/填充风格和对齐一致。为不熟悉或仅有图标的命令提供无障碍名称和工具提示。不要使用 Emoji 作为导航或命令图标。
 
 使用动效解释因果关系、层级和连续性：
 

references/windows-input-accessibility.md

@@ -27,7 +27,7 @@
 ## 2. 键盘与焦点
 
 - 将可操作元素放入 Tab 顺序；让标签和装饰元素退出该顺序。
-- 让 Tab 顺序与视觉和阅读顺序一致。优先使用自然 XAML 顺序，仅在纠正确认存在的问题时使用 `TabIndex`。
+- 让 Tab 顺序与视觉和阅读顺序一致。优先使用自然布局/声明顺序，仅在纠正确认存在的问题时显式覆盖焦点顺序。
 - 在列表、菜单、单选组、标签页和网格等复合控件内部使用方向键。
 - 窗口、页面、对话框或任务界面打开时，将初始焦点设置到最有用且安全的元素。
 - 浮出控件或对话框关闭时将焦点返回调用者。删除后，将焦点移动到可预测的相邻项或稳定容器。
@@ -84,8 +84,8 @@
 无障碍名称必须简洁，在上下文中足以区分，并对命令使用操作导向的表述。
 
 - 当标准控件根据可见文本生成的名称正确时，使用该默认名称。
-- 对仅有图标的按钮、有意义的图像、自定义绘制内容、含义不清的重复控件，或可见文本无法描述操作的控件，显式设置 `AutomationProperties.Name`。
-- 适用时，通过 `AutomationProperties.LabeledBy` 将表单标签与字段关联。
+- 对仅有图标的按钮、有意义的图像、自定义绘制内容、含义不清的重复控件，或可见文本无法描述操作的控件，通过目标框架的无障碍 API 显式设置名称。
+- 适用时，通过目标框架的标签关系把表单标签与字段关联。
 - 将补充说明放在帮助文本或无障碍描述中；不要把所有内容塞进名称。
 - 通过正确的控件或 AutomationPeer 公开选择、选中、展开、按下、只读、必填、无效、忙碌和禁用状态。
 - 标记装饰性图像和重复字形，避免产生噪音。