opc/win_ui_ux_design_skill
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Chinese localization

Browse Source
This commit is contained in:
QiuSW
2026-07-18 17:40:25 +08:00
parent 07c63cb565
commit 2ed513bc25
6 changed files with 465 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+55 -55
View File
@@ -1,86 +1,86 @@
--- ---
name: win-ui-ux-design name: win-ui-ux-design
description: Design, review, and implement professional Windows desktop UI/UX for WinUI 3, Windows App SDK, XAML, Fluent Design, and Windows-targeted Qt for Python applications using PySide or PyQt. Use when a task involves Windows desktop app shells or screens, Windows 桌面端界面, PySide6, PyQt6, PySide2, PyQt5, Qt Widgets, QML, navigation and windowing, title bars, NavigationView or framework-equivalent control selection, responsive XAML or Qt layouts, theme resources, QPalette or QSS, Mica or Acrylic, keyboard/mouse/touch interaction, accessibility, design-system specifications, UI audits, or translating designs into WinUI 3, PySide, or PyQt code. 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、键盘/鼠标/触控交互、无障碍、设计系统规范、UI 审查，或将设计转换为 WinUI 3、PySide 或 PyQt 代码时使用。
--- ---
# Windows Desktop UI/UX Design # Windows 桌面端 UI/UX 设计
Design for Windows as a keyboard-and-pointer-first, resizable, high-density desktop environment that may also receive touch and pen input. Prefer familiar platform behavior over ornamental novelty. 将 Windows 视为以键盘和指针为主、可调整窗口大小、信息密度较高，同时可能接收触控和笔输入的桌面环境。优先采用用户熟悉的平台行为，而不是装饰性的新奇效果。
## Follow the core rules ## 遵循核心规则
- Optimize the user's task flow before styling individual controls. - 先优化用户任务流程，再设计单个控件的样式。
- Prefer WinUI controls, system resources, and built-in interaction behavior before creating custom UI. - 优先使用 WinUI 控件、系统资源和内置交互行为，再考虑创建自定义 UI。
- Treat keyboard, pointer, touch, screen reader, scaling, theme, and high contrast as one experience rather than later adaptations. - 将键盘、指针、触控、屏幕阅读器、缩放、主题和高对比度视为同一体验，而不是后期适配项。
- Specify every meaningful state: default, hover, pressed, focus, selected, disabled, loading, empty, error, offline or unavailable, success, and undo when relevant. - 定义每个有意义的状态：默认、悬停、按下、焦点、选中、禁用、加载、空、错误、离线或不可用、成功，以及适用时的撤销。
- Use semantic tokens and theme resources. Never encode meaning with color alone or assume the light palette works in dark mode. - 使用语义化 Token 和主题资源。不得只用颜色表达含义，也不得假设浅色模式的配色可直接用于深色模式。
- Keep density appropriate for desktop work. Do not enlarge mobile patterns or hide routine commands behind touch-only gestures. - 保持适合桌面工作的界面密度。不要放大移动端模式，也不要把常用命令隐藏在仅触控手势中。
- Gate every API, control, and Toolkit recommendation by the project's Windows App SDK version, target OS, packaging model, and dependencies. - 根据项目的 Windows App SDK 版本、目标操作系统、打包模型和依赖项，对每个 API、控件和 Toolkit 建议设置版本门槛。
- Distinguish WinUI 3 (`Microsoft.UI.Xaml`) from UWP/WinUI 2 (`Windows.UI.Xaml`). Never copy APIs across them without verification. - 区分 WinUI 3（`Microsoft.UI.Xaml`）与 UWP/WinUI 2（`Windows.UI.Xaml`）。未经验证不得跨框架复制 API。
## Run the workflow ## 执行工作流
### 1. Establish constraints ### 1. 确立约束
Inspect the project before proposing implementation details. Determine: 在提出实现细节前检查项目。确定：
- framework and exact package versions; - 框架及其准确的软件包版本；
- minimum Windows version and packaged or unpackaged deployment; - 最低 Windows 版本，以及已打包或未打包的部署方式；
- primary tasks, audience, localization, data density, and accessibility needs; - 主要任务、目标用户、本地化、数据密度和无障碍需求；
- expected window sizes, multi-window behavior, and resize/snap scenarios; - 预期窗口尺寸、多窗口行为，以及调整大小和贴靠场景；
- primary input modes and whether touch optimization is required; - 主要输入方式，以及是否需要针对触控优化；
- brand constraints, light/dark behavior, and existing design tokens. - 品牌约束、浅色/深色行为和现有设计 Token。
If information is missing, state conservative assumptions and keep version-sensitive recommendations conditional. 如果信息缺失，明确说明保守假设，并让版本敏感的建议保持条件化。
### 2. Model the experience ### 2. 建模体验
Define the primary jobs, information hierarchy, window map, navigation model, and command surfaces. Keep top-level navigation shallow. Decide which work belongs in the main window, a secondary window, an inline surface, a flyout, or a modal dialog. 定义主要用户任务、信息层级、窗口图、导航模型和命令界面。保持顶级导航浅而清晰。确定哪些工作应放在主窗口、辅助窗口、内联界面、浮出控件或模态对话框中。
Describe the happy path and recovery paths before producing mockups or XAML. Preserve user context across navigation, resize, refresh, and errors. 先描述顺利路径和恢复路径，再制作原型或 XAML。在导航、调整大小、刷新和错误发生时保留用户上下文。
### 3. Define the visual system ### 3. 定义视觉系统
Create a small semantic system for type, spacing, geometry, color, elevation, material, icons, and motion. Use Windows defaults unless the brand requires a deliberate deviation. Read [windows-foundations.md](references/windows-foundations.md) for current Fluent principles, responsive breakpoints, theme, material, and motion guidance. 为字体、间距、几何、颜色、层级、材质、图标和动效建立精简的语义系统。除非品牌需要有意偏离，否则使用 Windows 默认规范。阅读 [windows-foundations.md](references/windows-foundations.md)，了解当前 Fluent 原则、响应式断点、主题、材质和动效指南。
### 4. Map intent to controls and patterns ### 4. 将意图映射到控件和模式
Select controls by interaction semantics, not by appearance or arbitrary item-count thresholds. Reuse commands across menus, toolbars, context menus, and accelerators. Read [controls-and-patterns.md](references/controls-and-patterns.md) before choosing navigation, collection, form, settings, feedback, or data-table patterns. 根据交互语义选择控件，而不是根据外观或任意的项目数量阈值。跨菜单、工具栏、上下文菜单和快捷键复用命令。选择导航、集合、表单、设置、反馈或数据表格模式前，阅读 [controls-and-patterns.md](references/controls-and-patterns.md)。
### 5. Specify interaction and accessibility ### 5. 规定交互与无障碍
Document focus order, arrow-key behavior, access keys, accelerators, pointer affordances, context menus, touch targets, drag alternatives, accessible names, announcements, contrast, and scaling. Read [input-accessibility.md](references/input-accessibility.md) for the required interaction and accessibility baseline. 记录焦点顺序、方向键行为、访问键、快捷键、指针提示、上下文菜单、触控目标、拖拽替代方式、无障碍名称、状态播报、对比度和缩放。阅读 [input-accessibility.md](references/input-accessibility.md)，了解必需的交互与无障碍基线。
### 6. Engineer and validate ### 6. 工程实现与验证
When implementation is requested, follow the existing architecture and centralize tokens, commands, and state. Preserve virtualization and avoid synchronous work on the UI thread. Read [engineering-validation.md](references/engineering-validation.md) for version gates, implementation practices, performance checks, and the test matrix. 请求实现时，遵循现有架构，并集中管理 Token、命令和状态。保留虚拟化，避免在 UI 线程上执行同步工作。阅读 [engineering-validation.md](references/engineering-validation.md)，了解版本门槛、实现实践、性能检查和测试矩阵。
Validate the result at realistic compact, medium, and wide window widths rather than only at a full-screen monitor resolution. 在真实的紧凑、中等和宽窗口宽度下验证结果，而不是只在全屏显示器分辨率下验证。
## Produce decision-ready output ## 产出可用于决策的结果
For a new design, provide: 对于新设计，提供：
1. assumptions and target scenarios; 1. 假设和目标场景；
2. information architecture and window/navigation model; 2. 信息架构与窗口/导航模型；
3. annotated layout with responsive behavior; 3. 带响应式行为说明的标注布局；
4. control and command mapping; 4. 控件和命令映射；
5. semantic visual tokens; 5. 语义化视觉 Token；
6. interaction and state matrix; 6. 交互与状态矩阵；
7. accessibility requirements; 7. 无障碍要求；
8. implementation notes and acceptance checks. 8. 实现说明和验收检查。
For a review, lead with findings ordered by severity. For each finding, identify the affected screen or control, user impact, violated Windows convention, and concrete correction. Separate correctness and accessibility defects from subjective polish suggestions. 对于评审，先按严重程度列出发现。每项发现都要指出受影响的界面或控件、用户影响、违反的 Windows 约定和具体修正方案。将正确性与无障碍缺陷同主观的视觉润色建议分开。
For implementation, change only the requested scope, reuse the project's patterns, build or run relevant checks, and report any API/version assumptions that remain unverified. 对于实现，只修改请求范围，复用项目现有模式，构建或运行相关检查，并报告任何仍未验证的 API 或版本假设。
## Reject common failure modes ## 拒绝常见失败模式
- Do not present obsolete UWP or archived Toolkit APIs as current WinUI 3 guidance. - 不要把过时的 UWP 或已归档 Toolkit API 当作当前 WinUI 3 指南。
- Do not recommend `ComboBox` for multiple selection; it does not support it. - 不要推荐使用 `ComboBox` 进行多选；它不支持多选。
- Do not assume the archived Windows Community Toolkit `DataGrid` is available in current WinUI 3 projects. - 不要假设当前 WinUI 3 项目中存在已归档的 Windows Community Toolkit `DataGrid`。
- Do not use emoji as structural interface icons; use platform glyphs or a consistent vector icon set. - 不要把 Emoji 用作结构性界面图标；使用平台字形或一致的矢量图标集。
- Do not force Acrylic onto every surface. Use materials to express hierarchy and provide readable solid fallbacks. - 不要强制在所有表面使用 Acrylic。用材质表达层级，并提供可读的纯色回退方案。
- Do not require `AutomationProperties.Name` where a standard control already exposes an accurate accessible name; add explicit names when semantics are otherwise missing. - 当标准控件已经公开准确的无障碍名称时，不要强制设置 `AutomationProperties.Name`；仅在缺少语义时显式添加名称。
- Do not confirm every deletion by default. Prefer undo for frequent, recoverable actions and reserve modal confirmation for costly or irreversible consequences. - 不要默认确认每次删除。对频繁且可恢复的操作优先提供撤销；仅对代价高或不可逆的后果使用模态确认。
- Do not hard-code one window size, theme, DPI, locale, or input method as the design baseline. - 不要把单一窗口尺寸、主题、DPI、区域设置或输入方式硬编码为设计基线。
agents/openai.yaml
+2 -2
View File
@@ -1,4 +1,4 @@
interface: interface:
display_name: "Windows UI/UX Design" display_name: "Windows UI/UX 设计"
short_description: "设计、评审并实现专业的 Windows 桌面端体验" short_description: "设计、评审并实现专业的 Windows 桌面端体验"
default_prompt: "Use $win-ui-ux-design to design and review a Windows desktop app experience." default_prompt: "使用 $win-ui-ux-design 设计并评审 Windows 桌面应用体验。"
references/controls-and-patterns.md
+109 -109
View File
@@ -1,163 +1,163 @@
# WinUI controls and desktop patterns # WinUI 控件与桌面端模式
## Contents ## 目录
1. Selection method 1. 选择方法
2. Navigation and window shell 2. 导航与窗口外壳
3. Collections and structured data 3. 集合与结构化数据
4. Input controls and forms 4. 输入控件与表单
5. Commands and menus 5. 命令与菜单
6. Feedback and transient surfaces 6. 反馈与临时界面
7. Common page patterns 7. 常见页面模式
8. Control review checklist 8. 控件评审检查清单
9. Official sources 9. 官方资料
## 1. Selection method ## 1. 选择方法
Choose controls by semantics and built-in behavior: 根据语义和内置行为选择控件：
1. Identify whether the user is navigating, selecting, invoking, editing, comparing, or inspecting. 1. 确定用户是在导航、选择、调用、编辑、比较还是检查。
2. Prefer the control that already implements the expected keyboard, focus, selection, automation, and theme behavior. 2. 优先选择已经实现预期键盘、焦点、选择、自动化和主题行为的控件。
3. Check availability against the exact Windows App SDK or Toolkit version. 3. 根据准确的 Windows App SDK 或 Toolkit 版本检查可用性。
4. Customize styles before templates; replace the control only if its interaction model is wrong. 4. 先自定义样式，再考虑模板；仅当交互模型不正确时才替换控件。
5. Record accessibility, localization, performance, maintenance, and licensing costs for third-party controls. 5. 记录第三方控件的无障碍、本地化、性能、维护和许可成本。
Do not choose a control from a screenshot alone. Two controls can look similar while exposing different semantics to keyboard and assistive technology. 不要仅凭截图选择控件。两个控件可能外观相似，却向键盘和辅助技术公开不同的语义。
## 2. Navigation and window shell ## 2. 导航与窗口外壳
| Intent | Use | Avoid | | 意图 | 使用 | 避免 |
|---|---|---| |---|---|---|
| Top-level app destinations | `NavigationView` | custom sidebar without Windows navigation behavior | | 应用顶级目标位置 | `NavigationView` | 缺少 Windows 导航行为的自定义侧栏 |
| Small set of static peer views | `SelectorBar` or a simple selector appropriate to content | document-style tabs for unrelated destinations | | 少量静态同级视图 | `SelectorBar` 或适合内容的简单选择器 | 用文档式标签页表示无关目标位置 |
| Open documents or closeable workspaces | `TabView` | `NavigationView` items masquerading as documents | | 打开的文档或可关闭工作区 | `TabView` | 让 `NavigationView` 项目伪装成文档 |
| Hierarchical location path | `BreadcrumbBar` | concatenated text and separators | | 分层位置路径 | `BreadcrumbBar` | 拼接文本和分隔符 |
| Hierarchical data | `TreeView` | recursively nested `ListView` controls | | 分层数据 | `TreeView` | 递归嵌套 `ListView` 控件 |
| List and selected item | list/details pattern | forcing every detail into a modal | | 列表与选中项 | 列表/详情模式 | 强制在模态窗口中显示所有详情 |
Keep top-level navigation shallow, stable, and labeled. Select top or left `NavigationView` by content breadth, localization, growth, window width, and command density—not a universal item-count rule. Let `PaneDisplayMode="Auto"` and control thresholds handle common adaptive behavior unless the experience requires deliberate states. 保持顶级导航浅、稳定且带标签。根据内容宽度、本地化、增长空间、窗口宽度和命令密度选择顶部或左侧 `NavigationView`，不要使用统一的项目数量规则。除非体验需要明确的自定义状态，否则让 `PaneDisplayMode="Auto"` 和控件阈值处理常见自适应行为。
Use `Frame` only when page navigation and a back stack match the experience. Preserve selection, filter, scroll, and unsaved state when navigating back. Do not show a back button if there is nowhere meaningful to go. 仅当页面导航和后退堆栈符合体验时使用 `Frame`。后退导航时保留选择、筛选、滚动和未保存状态。没有可返回位置时不要显示后退按钮。
For Windows App SDK 1.7 or later, prefer the WinUI `TitleBar` control for a customized title bar and coordinate it with `NavigationView`. On earlier versions, use the supported `Window.ExtendsContentIntoTitleBar` and `Window.SetTitleBar` path. Preserve caption buttons, drag regions, system menu access, active/inactive appearance, and resize behavior. 对于 Windows App SDK 1.7 或更高版本，优先使用 WinUI `TitleBar` 控件自定义标题栏，并与 `NavigationView` 协调。对于更早版本，使用受支持的 `Window.ExtendsContentIntoTitleBar` 和 `Window.SetTitleBar` 方案。保留标题按钮、拖动区域、系统菜单访问、活动/非活动外观和调整大小行为。
Use additional windows for genuinely parallel or detachable work, not as a replacement for information hierarchy. Define owner, activation, placement, close behavior, and state synchronization. 仅为真正并行或可分离的工作使用附加窗口，不要用它替代信息层级。定义所有者、激活、位置、关闭行为和状态同步。
## 3. Collections and structured data ## 3. 集合与结构化数据
| Need | Preferred option | Notes | | 需求 | 首选方案 | 说明 |
|---|---|---| |---|---|---|
| Text-heavy selectable collection | `ListView` | mature selection, grouping, reorder, and virtualization behavior | | 以文本为主的可选择集合 | `ListView` | 具有成熟的选择、分组、重排和虚拟化行为 |
| Uniform visual tiles | `GridView` | use a virtualizing items panel | | 统一的视觉磁贴 | `GridView` | 使用支持虚拟化的项目面板 |
| Flexible list/grid/custom layouts | `ItemsView` | modern composition with layout switching and built-in selection/accessibility | | 灵活的列表/网格/自定义布局 | `ItemsView` | 支持布局切换并内置选择和无障碍的现代组合方式 |
| Low-level custom virtualized layout | `ItemsRepeater` | selection, invocation, focus, and automation may need extra engineering | | 底层自定义虚拟化布局 | `ItemsRepeater` | 选择、调用、焦点和自动化可能需要额外工程工作 |
| Hierarchy | `TreeView` | supports single and multiple selection | | 层级 | `TreeView` | 支持单选和多选 |
| Simple read-only rows and columns | templated `ListView`/`ItemsView` | provide headers and accessible relationships | | 简单只读行列 | 模板化 `ListView`/`ItemsView` | 提供表头和无障碍关系 |
| Full spreadsheet-like editing | verified maintained table component | validate keyboard, UI Automation, virtualization, sorting, resize, and editing | | 完整的电子表格式编辑 | 经验证且持续维护的表格组件 | 验证键盘、UI Automation、虚拟化、排序、调整大小和编辑 |
Do not decide `ListView` versus a data table from a fixed threshold such as 20 rows. Base the choice on column relationships, comparison, sorting, editing, selection, virtualization, and keyboard navigation. 不要用“20 行”等固定阈值决定使用 `ListView` 还是数据表格。应根据列关系、比较、排序、编辑、选择、虚拟化和键盘导航来选择。
The Windows Community Toolkit `DataGrid` documentation is archived; it is not a current WCT 8+ WinUI 3 control. For new work, evaluate currently maintained options such as Toolkit Labs `DataTable` or the community `WinUI.TableView`, and explicitly verify their maturity and requirements. Do not silently introduce one. Windows Community Toolkit `DataGrid` 文档已归档；它不是当前 WCT 8+ 的 WinUI 3 控件。对于新项目，评估当前仍在维护的方案，例如 Toolkit Labs `DataTable` 或社区 `WinUI.TableView`，并明确验证其成熟度和要求。不得静默引入依赖。
Keep virtualization enabled for large or unbounded collections. Never replace a virtualizing panel with a generic panel without measuring the result. Provide loading, empty, filtered-empty, partial-data, stale, and load-failure states. 为大型或无上限集合保持虚拟化。未经测量，不要用通用面板替换虚拟化面板。提供加载、空、筛选后为空、部分数据、过期数据和加载失败状态。
For selection, support Windows conventions: click/tap for a single item, Ctrl for independent selection, Shift for ranges, Space for focused selection where the control supports it, and visible selection independent from keyboard focus. 选择行为应支持 Windows 约定：单击/点击选择单项，Ctrl 独立选择，Shift 范围选择，控件支持时用 Space 选择焦点项，并让可见选择状态与键盘焦点相互独立。
## 4. Input controls and forms ## 4. 输入控件与表单
| Intent | Use | Important distinction | | 意图 | 使用 | 重要区别 |
|---|---|---| |---|---|---|
| Short or multiline plain text | `TextBox` | use `AcceptsReturn` and suitable wrapping for multiline | | 短文本或多行纯文本 | `TextBox` | 多行使用 `AcceptsReturn` 和合适的换行方式 |
| Rich formatted editing | `RichEditBox` | do not use for plain multiline text | | 富格式编辑 | `RichEditBox` | 不要用于普通多行文本 |
| Numeric value | `NumberBox` | still validate range and domain constraints | | 数值 | `NumberBox` | 仍需验证范围和领域约束 |
| Date | `DatePicker` or `CalendarDatePicker` | choose persistent picker versus compact calendar entry | | 日期 | `DatePicker` 或 `CalendarDatePicker` | 在常驻选择器和紧凑日历输入间选择 |
| Time | `TimePicker` | respect locale formatting | | 时间 | `TimePicker` | 尊重区域格式 |
| Immediate on/off setting | `ToggleSwitch` | label the state clearly | | 立即生效的开/关设置 | `ToggleSwitch` | 清楚标记状态 |
| Selection in a form or batch list | `CheckBox` | supports checked, unchecked, and optional indeterminate semantics | | 表单或批量列表中的选择 | `CheckBox` | 支持选中、未选中和可选的不确定语义 |
| One visible option from a small set | grouped `RadioButton` controls | use `ComboBox` when space or option count makes scanning worse | | 从少量可见选项中单选 | 分组的 `RadioButton` 控件 | 当空间或选项数量降低扫描效率时使用 `ComboBox` |
| One option from a compact list | `ComboBox` | it does not support multiple selection | | 从紧凑列表中单选 | `ComboBox` | 不支持多选 |
| Multiple options | `ListView`, `ItemsView`, checked list, or purpose-built flyout | keep selected values reviewable | | 多选 | `ListView`、`ItemsView`、复选列表或专用浮出控件 | 让用户能够复查已选值 |
| Bounded continuous value | `Slider` | show current value and allow precise keyboard entry when needed | | 有界连续值 | `Slider` | 显示当前值，并在需要时允许精确键盘输入 |
| Rating | `RatingControl` | use only for genuine rating semantics | | 评分 | `RatingControl` | 仅用于真实的评分语义 |
Place labels where scan order remains clear under narrow widths, text scaling, and localization. Use `AutomationProperties.LabeledBy` when a separate label must be associated with a field. Mark required fields in text, not color alone. Provide constraints before entry, validate at a useful boundary such as blur or submit, and state both the problem and recovery. 将标签放在窄宽度、文本缩放和本地化后仍能保持清晰扫描顺序的位置。需要把独立标签关联到字段时，使用 `AutomationProperties.LabeledBy`。用文字而不是仅用颜色标记必填字段。输入前提供约束，在失焦或提交等合适边界验证，并同时说明问题和恢复方式。
Do not disable the primary action without explaining unmet requirements. Preserve user input on validation or network failure. For long forms, define draft, cancel, close, and unsaved-change behavior. 不要在不说明未满足要求的情况下禁用主要操作。验证或网络失败时保留用户输入。对于长表单，定义草稿、取消、关闭和未保存更改行为。
## 5. Commands and menus ## 5. 命令与菜单
Model a command once and expose it through suitable surfaces using `StandardUICommand`, `XamlUICommand`, or the project's `ICommand` pattern. 使用 `StandardUICommand`、`XamlUICommand` 或项目的 `ICommand` 模式，只建模一次命令，再通过合适的界面公开。
| Surface | Use | | 界面 | 使用方式 |
|---|---| |---|---|
| Primary page command | visible `Button` or `CommandBar` command | | 主要页面命令 | 可见的 `Button` 或 `CommandBar` 命令 |
| Document-centric application menus | `MenuBar` | | 以文档为中心的应用菜单 | `MenuBar` |
| Object-specific commands | `ContextFlyout`, preferably `CommandBarFlyout` when rich commands help | | 对象特定命令 | `ContextFlyout`；富命令有帮助时优先 `CommandBarFlyout` |
| Extra or low-frequency commands | secondary `CommandBar` commands or overflow menu | | 额外或低频命令 | 次要 `CommandBar` 命令或溢出菜单 |
| Split default/alternate action | `SplitButton` | | 拆分默认/备选操作 | `SplitButton` |
| Menu-only action set | `DropDownButton` or `MenuFlyout` | | 仅菜单操作集 | `DropDownButton` 或 `MenuFlyout` |
| Power-user path | `KeyboardAccelerator` plus tooltip/menu shortcut text | | 高级用户路径 | `KeyboardAccelerator` 加工具提示/菜单快捷键文本 |
Keep critical commands discoverable without hover or gestures. Include relevant contextual commands in a context menu so pointer, keyboard, touch, and assistive technology users have a common route. Use access keys for efficient Alt navigation and accelerators for repeated actions. 让关键命令无需悬停或手势即可发现。在上下文菜单中包含相关上下文命令，使指针、键盘、触控和辅助技术用户都有通用路径。使用访问键实现高效的 Alt 导航，使用快捷键执行重复操作。
Use specific action labels such as “Delete 3 files” rather than “OK”. Keep destructive commands spatially separated and show consequence. Offer undo when the action is common and reversible. 使用“删除 3 个文件”等具体操作标签，不要只写“确定”。让破坏性命令在空间上分离并显示后果。操作常见且可恢复时提供撤销。
## 6. Feedback and transient surfaces ## 6. 反馈与临时界面
| Need | Use | Guidance | | 需求 | 使用 | 指南 |
|---|---|---| |---|---|---|
| Inline status, warning, or recoverable error | `InfoBar` | keep visible while action is required; do not assume automatic dismissal | | 内联状态、警告或可恢复错误 | `InfoBar` | 需要操作时保持可见；不要假设会自动消失 |
| First-use education anchored to UI | `TeachingTip` | show sparingly and never for routine status | | 锚定到 UI 的首次使用教学 | `TeachingTip` | 谨慎展示，不要用于常规状态 |
| Blocking decision or irreversible consequence | `ContentDialog` | ask only when the app cannot safely choose or offer undo | | 阻塞式决策或不可逆后果 | `ContentDialog` | 仅当应用无法安全选择或无法提供撤销时询问 |
| Contextual options or detail | `Flyout` | dismissible and connected to its source | | 上下文选项或详情 | `Flyout` | 可解除，并与来源建立连接 |
| Determinate work | `ProgressBar` | report meaningful progress | | 确定性工作 | `ProgressBar` | 报告有意义的进度 |
| Indeterminate short wait | `ProgressRing` | keep surrounding context stable | | 不确定的短时等待 | `ProgressRing` | 保持周围上下文稳定 |
| Long/background work | in-page progress plus cancel/background affordance | do not trap users in a spinner | | 长时间/后台工作 | 页面内进度加取消/后台处理入口 | 不要让用户困在旋转指示器中 |
For frequent destructive actions, prefer immediate completion plus undo over repeated confirmation. For truly destructive dialogs, make the title state the decision and use explicit button verbs. 对于频繁的破坏性操作，优先立即完成并提供撤销，而不是反复确认。对于真正具有破坏性的对话框，让标题直接说明决策，并使用明确的按钮动词。
Every async surface needs a success, failure, timeout, retry or alternate path, and cancellation strategy when cancellation is meaningful. Avoid white screens and layout jumps; retain the previous content or use a shape-matched placeholder. 每个异步界面都需要成功、失败、超时、重试或替代路径；取消有意义时还需要取消策略。避免白屏和布局跳动；保留之前的内容或使用形状匹配的占位内容。
## 7. Common page patterns ## 7. 常见页面模式
### Application shell ### 应用外壳
Use title bar, top-level navigation, page header, contextual commands, and a content frame or presenter. Keep title-bar drag regions separate from interactive navigation and search controls. 使用标题栏、顶级导航、页面标题、上下文命令和内容 Frame 或 Presenter。让标题栏拖动区域与交互式导航和搜索控件分离。
### Settings ### 设置
Use Windows Community Toolkit `SettingsCard` and `SettingsExpander` only after verifying the installed Toolkit package. Group by user intent, add descriptions for non-obvious consequences, and make reversible preferences apply immediately. Use Apply, restart, or confirmation only when a change is expensive, delayed, security-sensitive, or not safely reversible. 仅在验证已安装 Toolkit 软件包后使用 Windows Community Toolkit `SettingsCard` 和 `SettingsExpander`。按用户意图分组，为不明显的后果添加说明，并让可恢复偏好立即生效。仅当更改代价高、延迟生效、涉及安全或无法安全恢复时使用“应用”、重启或确认。
### List/details ### 列表/详情
At wide widths, show list and details together. At compact widths, navigate between them while preserving list selection, scroll, filter, and keyboard focus. Define what happens when the selected item is deleted, filtered out, or fails to load. 在宽窗口中同时显示列表和详情。在紧凑窗口中于两者间导航，同时保留列表选择、滚动、筛选和键盘焦点。定义选中项被删除、被筛选掉或加载失败时的行为。
### Form or editor ### 表单或编辑器
Use a predictable scan path, keep related controls together, align actions consistently, and reserve space for validation. Make save state explicit: saved, saving, unsaved, conflict, offline, or failed. Provide undo/redo for document-like work. 使用可预测的扫描路径，将相关控件分组，保持操作对齐一致，并为验证预留空间。明确保存状态：已保存、正在保存、未保存、冲突、离线或失败。为文档式工作提供撤销/重做。
### Empty and error states ### 空状态与错误状态
State what happened, why when known, and what the user can do next. Tailor empty states: first-use empty, filtered empty, permission denied, disconnected, and failed loading are different problems. 说明发生了什么、已知时说明原因，以及用户下一步能做什么。区分空状态：首次使用为空、筛选后为空、权限被拒绝、断开连接和加载失败是不同问题。
## 8. Control review checklist ## 8. 控件评审检查清单
- [ ] Each control matches the user's intent and exposes correct semantics. - [ ] 每个控件都匹配用户意图并公开正确语义。
- [ ] All APIs and dependencies exist in the project's versions. - [ ] 所有 API 和依赖项都存在于项目使用的版本中。
- [ ] Navigation, selection, focus, and back behavior are defined. - [ ] 已定义导航、选择、焦点和后退行为。
- [ ] Contextual commands have a non-hover route. - [ ] 上下文命令具有无需悬停的访问路径。
- [ ] Collection virtualization and keyboard behavior are preserved. - [ ] 集合虚拟化和键盘行为得到保留。
- [ ] Forms retain input and provide actionable validation. - [ ] 表单保留输入并提供可操作的验证信息。
- [ ] Dialogs are limited to genuinely blocking decisions. - [ ] 对话框仅用于真正需要阻塞的决策。
- [ ] Loading, empty, error, timeout, cancellation, and undo states are handled. - [ ] 已处理加载、空、错误、超时、取消和撤销状态。
## 9. Official sources ## 9. 官方资料
- [Controls for Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/controls/) - [Windows 应用控件](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview) - [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view) - [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview) - [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
- [Commanding](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding) - [命令系统](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
- [Dialogs and flyouts](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/) - [对话框与浮出控件](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
- [App settings guidelines](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings) - [应用设置指南](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
- [Archived WCT DataGrid status](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid) - [已归档 WCT DataGrid 状态](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
references/engineering-validation.md
+104 -104
View File
@@ -1,143 +1,143 @@
# WinUI engineering and validation # WinUI 工程实现与验证
## Contents ## 目录
1. Version and dependency gates 1. 版本与依赖门槛
2. XAML and state architecture 2. XAML 与状态架构
3. Windowing and responsive implementation 3. 窗口化与响应式实现
4. Performance and async behavior 4. 性能与异步行为
5. Implementation review 5. 实现评审
6. Release test matrix 6. 发布测试矩阵
7. Severity model 7. 严重程度模型
8. Official sources 8. 官方资料
## 1. Version and dependency gates ## 1. 版本与依赖门槛
Before generating XAML or C#: 生成 XAML 或 C# 前：
1. Read the project file, central package props, target framework, target/min Windows versions, and installed packages. 1. 阅读项目文件、中央软件包属性、目标框架、目标/最低 Windows 版本和已安装软件包。
2. Identify the Windows App SDK and Windows Community Toolkit versions exactly. 2. 准确确定 Windows App SDK 和 Windows Community Toolkit 版本。
3. Check whether the project is packaged or unpackaged and whether it uses single-project MSIX. 3. 检查项目是已打包还是未打包，以及是否使用单项目 MSIX。
4. Verify the proposed API in current Microsoft documentation and, for controls, the WinUI 3 Gallery. 4. 在当前 Microsoft 文档中验证建议的 API；对于控件，还要在 WinUI 3 Gallery 中验证。
5. Record minimum-version and fallback behavior in the recommendation. 5. 在建议中记录最低版本和回退行为。
Use `Microsoft.UI.Xaml` for WinUI 3. Treat examples using `Windows.UI.Xaml`, WinUI 2 Gallery, or UWP-specific APIs as migration inputs, not copy-ready code. WinUI 3 使用 `Microsoft.UI.Xaml`。将使用 `Windows.UI.Xaml`、WinUI 2 Gallery 或 UWP 特有 API 的示例视为迁移参考，而不是可直接复制的代码。
Examples of version-sensitive guidance: 版本敏感指南示例：
- the WinUI `TitleBar` control requires Windows App SDK 1.7 or later; - WinUI `TitleBar` 控件需要 Windows App SDK 1.7 或更高版本；
- `SystemBackdropElement` requires Windows App SDK 1.6.3 or later; - `SystemBackdropElement` 需要 Windows App SDK 1.6.3 或更高版本；
- Mica requires Windows 11 and falls back to a solid theme surface on Windows 10; - Mica 需要 Windows 11，在 Windows 10 回退为纯色主题表面；
- Windows Community Toolkit `DataGrid` is archived and not a WCT 8+ WinUI 3 control. - Windows Community Toolkit `DataGrid` 已归档，并非 WCT 8+ 的 WinUI 3 控件。
For any third-party control, document package, version, license, maintenance status, supported Windows versions, theme/high-contrast behavior, UI Automation support, keyboard model, localization, virtualization, and escape plan. 对于任何第三方控件，记录软件包、版本、许可证、维护状态、支持的 Windows 版本、主题/高对比度行为、UI Automation 支持、键盘模型、本地化、虚拟化和退出方案。
## 2. XAML and state architecture ## 2. XAML 与状态架构
- Follow the project's MVVM or code-behind conventions; do not introduce a second architecture for one screen. - 遵循项目现有的 MVVM 或代码隐藏约定；不要为一个界面引入第二套架构。
- Represent user actions as reusable commands when the same action appears in buttons, menus, context menus, and accelerators. - 当同一操作出现在按钮、菜单、上下文菜单和快捷键中时，将用户操作表示为可复用命令。
- Keep view state explicit: idle, loading, content, empty, filtered empty, error, offline/stale, permission denied, and partial result as applicable. - 根据场景明确表示视图状态：空闲、加载、内容、空、筛选后为空、错误、离线/过期、权限被拒绝和部分结果。
- Centralize semantic colors, type styles, spacing, geometry, icon sizes, and motion in resource dictionaries. - 在资源字典中集中管理语义颜色、文本样式、间距、几何、图标大小和动效。
- Use `ThemeResource` for values that must change while the app is running and `StaticResource` only when runtime theme updates are not required. - 需要在应用运行时变化的值使用 `ThemeResource`；仅当不需要运行时主题更新时使用 `StaticResource`。
- Put light, dark, and high-contrast mappings in theme dictionaries when custom tokens are necessary. - 需要自定义 Token 时，在主题字典中放置浅色、深色和高对比度映射。
- Prefer styles and composition over copying full control templates. A custom template inherits responsibility for every visual and accessibility state. - 优先使用样式和组合，不要复制完整控件模板。自定义模板将承担所有视觉和无障碍状态的实现责任。
- Use `x:Bind` or the project's established binding approach consistently. Make binding mode and update timing explicit for editable values. - 一致使用 `x:Bind` 或项目既有的绑定方式。为可编辑值明确绑定模式和更新时间。
- Use Grid and flexible sizing for structured layouts; avoid deep nested panels and fixed sizes that break localization or text scaling. - 结构化布局使用 Grid 和弹性尺寸；避免深层嵌套面板，以及会破坏本地化或文本缩放的固定尺寸。
- Keep visual order aligned with reading and tab order. - 让视觉顺序与阅读和 Tab 顺序一致。
Do not write UI-thread dispatching as a substitute for sound async ownership. Marshal only the final state update that truly requires the UI thread and ensure the view is still alive. 不要用 UI 线程调度掩盖不合理的异步所有权。只封送真正需要 UI 线程的最终状态更新，并确保视图仍然存在。
## 3. Windowing and responsive implementation ## 3. 窗口化与响应式实现
### Title bar ### 标题栏
Keep system caption buttons and the system menu. Define a drag region along the top edge, exclude interactive children from drag regions, and test active/inactive appearance. Verify maximize, restore, resize, Snap Layouts, touch, right-click system menu, and high contrast. 保留系统标题按钮和系统菜单。沿应用画布顶部定义拖动区域，将交互式子元素排除在拖动区域外，并测试活动/非活动外观。验证最大化、还原、调整大小、Snap Layouts、触控、右键系统菜单和高对比度。
Prefer the platform `TitleBar` control when the project version supports it. When using `NavigationView` with that control, let one component own back and pane-toggle behavior rather than showing duplicate buttons. 项目版本支持时，优先使用平台 `TitleBar` 控件。与 `NavigationView` 一起使用时，让一个组件负责后退和窗格切换行为，不要显示重复按钮。
### Responsive layout ### 响应式布局
Start with a safe compact layout and add wider visual states. Use effective window/content width. Test each transition in both directions and preserve: 从安全的紧凑布局开始，再添加较宽的视觉状态。使用有效窗口/内容宽度。双向测试每个转换并保留：
- selection and keyboard focus; - 选择和键盘焦点；
- scroll position and expanded state; - 滚动位置和展开状态；
- input and validation state; - 输入和验证状态；
- command availability; - 命令可用性；
- accessible reading order. - 无障碍阅读顺序。
Avoid replacing the whole visual tree on every resize if a reflow or reposition is sufficient. Debounce expensive resize-driven work and never rebuild data collections solely because the window crossed a breakpoint. 如果重排或重新定位已足够，不要在每次调整大小时替换整个可视化树。对昂贵的大小调整工作进行防抖，不要只因为窗口跨越断点就重建数据集合。
### Multi-window ### 多窗口
Define ownership, activation, persisted placement, minimum size, close confirmation, and shared data lifetime. Ensure commands act on the active document/window context and that dialogs have the correct XamlRoot/owner. 定义所有权、激活、持久化位置、最小尺寸、关闭确认和共享数据生命周期。确保命令作用于活动文档/窗口上下文，并让对话框具有正确的 XamlRoot/所有者。
## 4. Performance and async behavior ## 4. 性能与异步行为
- Keep collection virtualization enabled and measure with realistic data, images, templates, and grouping. - 保持集合虚拟化，并使用真实数据、图像、模板和分组进行测量。
- Prefer `ListView`, `GridView`, or `ItemsView` behavior before low-level `ItemsRepeater` customization. - 在底层自定义 `ItemsRepeater` 前，优先使用 `ListView`、`GridView` 或 `ItemsView` 的行为。
- Decode images near their rendered size, avoid loading full-resolution assets for thumbnails, and cancel work for recycled items. - 按接近渲染尺寸解码图像，避免为缩略图加载全分辨率资源，并取消已回收项目的工作。
- Avoid synchronous file, network, database, or expensive serialization work on the UI thread. - 避免在 UI 线程上执行同步文件、网络、数据库或昂贵的序列化工作。
- Make async commands idempotent or prevent duplicate invocation while work is active. - 让异步命令具备幂等性，或在工作进行时阻止重复调用。
- Support cancellation for long operations and ignore stale results after navigation, search-query changes, or window close. - 支持取消长时间操作；导航、搜索查询变化或窗口关闭后忽略过期结果。
- Show immediate command feedback. Delay large skeleton/progress transitions just enough to avoid flicker for near-instant work, while never leaving the UI apparently frozen. - 立即提供命令反馈。对接近瞬时完成的工作，可轻微延迟大型骨架屏/进度过渡以避免闪烁，但绝不能让 UI 看起来冻结。
- Keep previous usable content visible during refresh when safe; distinguish refresh from first load. - 安全时在刷新期间保留之前可用的内容；区分刷新和首次加载。
- Animate opacity and transforms where possible; avoid layout-heavy animation across large trees. - 尽可能为不透明度和变换设置动画；避免对大型可视化树使用引发布局的动画。
- Defer expensive secondary content until requested, but do not lazy-load controls required for keyboard order or core task comprehension without a plan. - 将昂贵的次要内容延迟到请求时加载，但没有明确方案时，不要延迟加载键盘顺序或核心任务理解所需的控件。
- Measure startup, navigation, resize, input latency, scroll smoothness, memory growth, and recovery from device/theme changes. - 测量启动、导航、调整大小、输入延迟、滚动流畅度、内存增长，以及设备/主题变化后的恢复。
## 5. Implementation review ## 5. 实现评审
Check correctness before visual polish: 先检查正确性，再评审视觉润色：
- [ ] Namespace, APIs, package versions, and minimum OS are valid. - [ ] 命名空间、API、软件包版本和最低操作系统有效。
- [ ] The project builds without introducing warnings in the changed scope. - [ ] 项目能够构建，且未在修改范围内引入警告。
- [ ] Commands cannot double-submit and failures preserve user work. - [ ] 命令不会重复提交，失败时保留用户工作。
- [ ] Every data surface has loading, empty, error, and retry behavior as needed. - [ ] 每个数据界面根据需要具有加载、空、错误和重试行为。
- [ ] Virtualization, recycling, and cancellation work with production-scale data. - [ ] 虚拟化、回收和取消能处理生产规模数据。
- [ ] Theme resources update at runtime and custom tokens cover high contrast. - [ ] 主题资源在运行时更新，自定义 Token 覆盖高对比度。
- [ ] Layout survives compact width, long strings, text scaling, and display scaling. - [ ] 布局能够承受紧凑宽度、长字符串、文本缩放和显示缩放。
- [ ] Focus, selection, accessible names, roles, states, and announcements are correct. - [ ] 焦点、选择、无障碍名称、角色、状态和播报正确。
- [ ] Caption controls, drag regions, dialogs, and multi-window ownership behave correctly. - [ ] 标题按钮、拖动区域、对话框和多窗口所有权行为正确。
- [ ] Destructive actions use undo or confirmation proportional to consequence. - [ ] 破坏性操作使用与后果成比例的撤销或确认。
## 6. Release test matrix ## 6. 发布测试矩阵
Test representative combinations rather than one happy-path machine: 测试代表性组合，而不是只测试一台理想机器：
| Dimension | Minimum coverage | | 维度 | 最低覆盖范围 |
|---|---| |---|---|
| Windows | minimum supported OS plus current Windows 11 | | Windows | 最低支持的操作系统和当前 Windows 11 |
| Window | supported minimum, small `<=640` epx, medium `641–1007`, large `>=1008`, snapped, maximized | | 窗口 | 支持的最小尺寸、小 `<=640` epx、中 `641–1007`、大 `>=1008`、贴靠、最大化 |
| Scale | common 100%, 125%, 150%, 200% display scales and monitor transitions | | 缩放 | 常见的 100%、125%、150%、200% 显示缩放和显示器切换 |
| Text | default and increased Windows text size | | 文本 | 默认和增大的 Windows 文本大小 |
| Theme | light, dark, high contrast; transparency on and off | | 主题 | 浅色、深色、高对比度；透明效果开启和关闭 |
| Input | keyboard only, mouse, touch/pen when claimed | | 输入 | 仅键盘、鼠标，以及产品声明支持时的触控/笔 |
| Assistive tech | Narrator, Magnifier, Accessibility Insights/Inspect | | 辅助技术 | Narrator、放大镜、Accessibility Insights/Inspect |
| Content | empty, one item, realistic data, very large data, long localized strings, failures | | 内容 | 空、单项、真实数据、超大数据、长本地化字符串、失败 |
| Environment | slow storage/network, offline, permission denied, RDP or material fallback where relevant | | 环境 | 慢速存储/网络、离线、权限被拒绝、相关时的 RDP 或材质回退 |
| Lifecycle | suspend/close if applicable, reopen, upgrade, secondary-window close, crash-safe data recovery | | 生命周期 | 适用时的挂起/关闭、重新打开、升级、辅助窗口关闭、崩溃安全的数据恢复 |
Automate stable checks, but keep human review for Narrator flow, focus visibility, touch comfort, motion, wording, hierarchy, and perceived responsiveness. 自动执行稳定检查，但为 Narrator 流程、焦点可见性、触控舒适度、动效、文案、层级和感知响应速度保留人工评审。
## 7. Severity model ## 7. 严重程度模型
Use this order when reviewing a design or implementation: 评审设计或实现时使用以下顺序：
| Severity | Definition | Examples | | 严重程度 | 定义 | 示例 |
|---|---|---| |---|---|---|
| Blocker | Prevents a primary task, excludes an input/accessibility mode, loses data, or uses an unavailable API | keyboard trap, clipped save button, archived control assumed present | | 阻断 | 阻止主要任务、排除某种输入/无障碍方式、丢失数据或使用不可用 API | 键盘陷阱、保存按钮被裁切、假设已归档控件仍存在 |
| Major | Causes frequent error, disorientation, inaccessible content, or severe responsive/performance failure | broken focus return, nonvirtualized large list, unreadable dark mode | | 严重 | 导致频繁错误、迷失方向、内容不可访问，或严重的响应式/性能问题 | 焦点返回错误、大型列表未虚拟化、深色模式不可读 |
| Moderate | Slows tasks or creates inconsistent Windows behavior with a workaround | hidden contextual command, weak empty state, inconsistent selection | | 中等 | 降低任务效率，或产生虽有替代方案但不一致的 Windows 行为 | 隐藏上下文命令、空状态薄弱、选择行为不一致 |
| Minor | Polish issue with little task impact | spacing drift, inconsistent icon weight, unnecessary shadow | | 轻微 | 对任务影响很小的润色问题 | 间距偏差、图标字重不一致、不必要的阴影 |
For each finding, cite the screen/control, trigger condition, user impact, and smallest robust correction. Avoid vague feedback such as “make it more modern.” 每项发现都要指出界面/控件、触发条件、用户影响和最小稳健修正方案。避免“让它更现代”等模糊反馈。
## 8. Official sources ## 8. 官方资料
- [WinUI 3 overview](https://learn.microsoft.com/windows/apps/winui/winui3/) - [WinUI 3 概述](https://learn.microsoft.com/windows/apps/winui/winui3/)
- [Title bar customization](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3) - [标题栏自定义](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
- [NavigationView title bar integration](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview) - [NavigationView 标题栏集成](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
- [Responsive layouts with XAML](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml) - [使用 XAML 的响应式布局](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
- [ListView and GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview) - [ListView 与 GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials) - [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
- [Accessibility checklist](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist) - [无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
references/input-accessibility.md
+105 -105
View File
@@ -1,142 +1,142 @@
# Windows input and accessibility baseline # Windows 输入与无障碍基线
## Contents ## 目录
1. Input parity 1. 输入等价性
2. Keyboard and focus 2. 键盘与焦点
3. Mouse, touch, pen, and drag 3. 鼠标、触控、笔与拖拽
4. UI Automation semantics 4. UI Automation 语义
5. Visual and cognitive accessibility 5. 视觉与认知无障碍
6. Status, errors, and timing 6. 状态、错误与计时
7. Accessibility test matrix 7. 无障碍测试矩阵
8. Official sources 8. 官方资料
## 1. Input parity ## 1. 输入等价性
Make every primary scenario possible with keyboard alone. Pointer hover, right-click, touch swipe, pen barrel button, drag-and-drop, and gestures may accelerate a task but must not be the only way to complete it. 确保所有主要场景都能只用键盘完成。指针悬停、右键、触控轻扫、笔桶形按钮、拖放和手势可以加速任务，但不得成为完成任务的唯一方式。
Use standard controls first because they already implement much of the focus, keyboard, pointer, touch, and UI Automation behavior. For every custom control, define: 优先使用标准控件，因为它们已经实现大量焦点、键盘、指针、触控和 UI Automation 行为。为每个自定义控件定义：
- automation role, name, value, state, and supported patterns; - 自动化角色、名称、值、状态和支持的模式；
- tab-stop and inner arrow-key behavior; - Tab 停靠点和内部方向键行为；
- keyboard activation and Escape behavior; - 键盘激活和 Escape 行为；
- pointer cursor, hover, press, and context menu behavior; - 指针光标、悬停、按下和上下文菜单行为；
- touch target, manipulation threshold, and gesture alternative; - 触控目标、操作阈值和手势替代方式；
- focus visuals, selected visuals, and high-contrast rendering. - 焦点视觉、选中视觉和高对比度渲染。
## 2. Keyboard and focus ## 2. 键盘与焦点
- Put actionable elements in the tab sequence; keep labels and decorative elements out. - 将可操作元素放入 Tab 顺序；让标签和装饰元素退出该顺序。
- Match tab order to visual and reading order. Prefer natural XAML order and use `TabIndex` only to correct a demonstrated issue. - 让 Tab 顺序与视觉和阅读顺序一致。优先使用自然 XAML 顺序，仅在纠正确认存在的问题时使用 `TabIndex`。
- Use arrow keys inside composite controls such as lists, menus, radio groups, tabs, and grids. - 在列表、菜单、单选组、标签页和网格等复合控件内部使用方向键。
- Set initial focus to the most useful safe element when a window, page, dialog, or task surface opens. - 窗口、页面、对话框或任务界面打开时，将初始焦点设置到最有用且安全的元素。
- Return focus to the invoker when a flyout or dialog closes. After deletion, move focus to a predictable adjacent item or stable container. - 浮出控件或对话框关闭时将焦点返回调用者。删除后，将焦点移动到可预测的相邻项或稳定容器。
- Keep the platform focus visual visible. Do not encode focus only through a subtle color change. - 保持平台焦点视觉可见。不要只用轻微颜色变化表达焦点。
- Use access keys for visible commands and form navigation; use keyboard accelerators for frequent or standard actions. - 为可见命令和表单导航使用访问键；为频繁或标准操作使用键盘快捷键。
- Show accelerators in menus and tooltips where users learn commands. - 在菜单和工具提示中显示快捷键，帮助用户学习命令。
- Allow Escape to close dismissible UI or cancel the current transient mode. Do not discard unsaved work silently. - 允许 Escape 关闭可解除界面或取消当前临时模式。不得静默丢弃未保存工作。
- Ensure Enter and Space activate controls according to standard control behavior; do not invent conflicting key semantics. - 确保 Enter 和 Space 按标准控件行为激活控件；不要发明冲突的按键语义。
Use familiar shortcuts only when the command truly has the familiar meaning: 仅当命令真正具有熟悉含义时使用常见快捷键：
| Shortcut | Expected meaning | | 快捷键 | 预期含义 |
|---|---| |---|---|
| `Ctrl+N` | new item/document/window as appropriate | | `Ctrl+N` | 根据场景新建项目/文档/窗口 |
| `Ctrl+O` | open | | `Ctrl+O` | 打开 |
| `Ctrl+S` | save | | `Ctrl+S` | 保存 |
| `Ctrl+Z` / `Ctrl+Y` or `Ctrl+Shift+Z` | undo / redo, consistent with the app domain | | `Ctrl+Z` / `Ctrl+Y` 或 `Ctrl+Shift+Z` | 撤销/重做，并与应用领域保持一致 |
| `Ctrl+F` | search or find | | `Ctrl+F` | 搜索或查找 |
| `F5` | refresh when refresh is meaningful | | `F5` | 在刷新有意义时刷新 |
| `Delete` | delete selected item, with undo or confirmation based on consequence | | `Delete` | 删除选中项，并根据后果提供撤销或确认 |
| `Alt+Left` | back when the app has navigation history | | `Alt+Left` | 应用存在导航历史时后退 |
| `F6` | move between major panes in complex workspaces | | `F6` | 在复杂工作区的主要窗格间移动 |
Do not override operating-system or assistive-technology shortcuts. 不要覆盖操作系统或辅助技术快捷键。
## 3. Mouse, touch, pen, and drag ## 3. 鼠标、触控、笔与拖拽
### Mouse and pointer ### 鼠标与指针
- Use hover to preview or accelerate, never to hide the only route to a command. - 使用悬停进行预览或加速，但不要把命令的唯一入口隐藏在悬停中。
- Provide a context menu for object-specific commands; expose frequent commands visibly as well. - 为对象特定命令提供上下文菜单，同时让频繁命令保持可见。
- Use tooltips for unfamiliar icons, truncated content, and shortcut education—not for essential instructions. - 将工具提示用于不熟悉的图标、截断内容和快捷键教学，不要用于关键说明。
- Keep selection and focus visually distinct in dense lists and grids. - 在高密度列表和网格中，让选择与焦点在视觉上可区分。
- Preserve target position during hover and press; avoid geometry changes that make the pointer chase a control. - 悬停和按下时保持目标位置稳定；避免几何变化迫使指针追逐控件。
### Touch and pen ### 触控与笔
Use platform controls at their default size where possible. For custom targets, meet the Windows touch baseline: 尽可能使用平台控件的默认尺寸。自定义目标应满足 Windows 触控基线：
- target at least 40 × 40 epx, even if the visible glyph is smaller; - 目标至少为 40 × 40 epx，即使可见字形更小；
- a 32 epx-tall target can be acceptable when it is at least 120 epx wide; - 高度为 32 epx 的目标，在宽度至少 120 epx 时可以接受；
- for touch-optimized experiences, prefer 44 × 44 epx with at least 4 epx visible separation; - 针对触控优化的体验，优先使用 44 × 44 epx，并保持至少 4 epx 可见间距；
- enlarge frequent or high-consequence targets beyond the minimum; - 让频繁使用或误操作后果严重的目标大于最低尺寸；
- do not place destructive targets tightly beside routine actions. - 不要让破坏性目标紧邻常规操作。
Support mouse precision without making touch impossible. Make scrolling, zoom, selection, and pen input coexist without gesture conflicts. 在支持鼠标精确操作的同时保证触控可用。让滚动、缩放、选择和笔输入共存且不产生手势冲突。
### Drag and drop ### 拖放
Show a clear drag affordance, valid targets, insertion position, forbidden states, and completion feedback. Use a movement threshold to prevent accidental drags. Always provide keyboard and menu commands such as Move up/down, Move to, Attach, or Import for critical drag operations. 显示清晰的拖动提示、有效目标、插入位置、禁止状态和完成反馈。使用移动阈值避免误拖。对于关键拖动操作，始终提供“上移/下移”“移动到”“附加”或“导入”等键盘和菜单命令。
## 4. UI Automation semantics ## 4. UI Automation 语义
Accessible names must be concise, unique enough in context, and action-oriented for commands. 无障碍名称必须简洁，在上下文中足以区分，并对命令使用操作导向的表述。
- Let standard controls promote visible text when that produces the correct name. - 当标准控件根据可见文本生成的名称正确时，使用该默认名称。
- Set `AutomationProperties.Name` explicitly for icon-only buttons, meaningful images, custom-drawn content, ambiguous repeated controls, or controls whose visible text does not describe the action. - 对仅有图标的按钮、有意义的图像、自定义绘制内容、含义不清的重复控件，或可见文本无法描述操作的控件，显式设置 `AutomationProperties.Name`。
- Associate form labels with fields through `AutomationProperties.LabeledBy` where applicable. - 适用时，通过 `AutomationProperties.LabeledBy` 将表单标签与字段关联。
- Put supplemental instructions in help text or accessible descriptions; do not stuff them into the name. - 将补充说明放在帮助文本或无障碍描述中；不要把所有内容塞进名称。
- Expose selection, checked, expanded, pressed, read-only, required, invalid, busy, and disabled states through the correct control or automation peer. - 通过正确的控件或 AutomationPeer 公开选择、选中、展开、按下、只读、必填、无效、忙碌和禁用状态。
- Mark decorative images and duplicate glyphs so they do not create noise. - 标记装饰性图像和重复字形，避免产生噪音。
- Implement the appropriate UI Automation patterns for custom controls; an accessible name alone is insufficient. - 为自定义控件实现合适的 UI Automation 模式；只有无障碍名称并不充分。
Do not add an explicit name to every control mechanically. Duplicate or stale names can make the screen-reader experience worse. 不要机械地为每个控件添加显式名称。重复或过期的名称会使屏幕阅读器体验更差。
## 5. Visual and cognitive accessibility ## 5. 视觉与认知无障碍
- Maintain at least 4.5:1 text contrast in the normal light and dark themes. - 在普通浅色和深色主题中保持至少 4.5:1 的文本对比度。
- Test high contrast; do not use a high-contrast theme as a substitute for adequate normal-theme contrast. - 测试高对比度；不要把高对比度主题当作普通主题对比度不足的补救方法。
- Pair color with text, shape, icon, position, or pattern for errors, selection, and status. - 对错误、选择和状态，除颜色外同时使用文本、形状、图标、位置或图案。
- Preserve visible focus, current selection, and input validation at all theme states. - 在所有主题状态中保持焦点、当前选择和输入验证清晰可见。
- Support Windows text-size settings and display scaling without clipped text, inaccessible controls, or lost commands. - 支持 Windows 文本大小设置和显示缩放，不能出现文本裁切、控件不可访问或命令丢失。
- Prefer wrapping and adaptive height to truncation. Test long localized strings, narrow windows, and right-to-left layout when the product supports such locales. - 优先使用换行和自适应高度而不是截断。产品支持相关区域时，测试长本地化字符串、窄窗口和从右到左布局。
- Use plain, specific writing. Put the decision or recovery action first; avoid blame and error codes without explanation. - 使用平实、具体的文案。先给出决策或恢复操作；避免指责用户，也不要只显示错误代码而不解释。
- Avoid flashing and nonessential repetitive animation. Respect system animation preferences and keep interaction possible while motion runs. - 避免闪烁和非必要的重复动画。尊重系统动画偏好，并在动效运行时保持可交互。
- Provide captions or transcripts for meaningful audio/video and text alternatives for informative graphics. - 为有意义的音频/视频提供字幕或文字稿，为信息性图形提供文本替代内容。
## 6. Status, errors, and timing ## 6. 状态、错误与计时
Announce important asynchronous state changes without stealing focus. Use a suitable live-region or standard control behavior for loading completion, errors, and background status. 播报重要的异步状态变化，但不要抢夺焦点。为加载完成、错误和后台状态使用合适的实时区域或标准控件行为。
Error feedback must answer: 错误反馈必须回答：
1. What failed? 1. 什么失败了？
2. What user work was preserved? 2. 用户的哪些工作已保留？
3. What can the user do now? 3. 用户现在可以做什么？
Place field errors near the field and summarize multiple errors at the task level when useful. Move focus only when it helps recovery, such as focusing the first invalid field after submit. 将字段错误放在字段附近；有多个错误时，根据需要在任务层级汇总。仅在有助于恢复时移动焦点，例如提交后聚焦第一个无效字段。
Do not auto-dismiss critical errors. Give users enough time to read transient status, pause time limits when feasible, and provide a persistent history for important background operations or notifications. 不要自动关闭关键错误。给用户足够时间阅读临时状态；可行时暂停时间限制，并为重要后台操作或通知提供持久历史记录。
## 7. Accessibility test matrix ## 7. 无障碍测试矩阵
- [ ] Complete primary flows with keyboard only. - [ ] 只使用键盘完成主要流程。
- [ ] Verify logical Tab, Shift+Tab, arrow, Enter, Space, Escape, access-key, and accelerator behavior. - [ ] 验证合理的 Tab、Shift+Tab、方向键、Enter、Space、Escape、访问键和快捷键行为。
- [ ] Test Narrator reading order, names, roles, values, states, and live announcements. - [ ] 测试 Narrator 阅读顺序、名称、角色、值、状态和实时播报。
- [ ] Inspect the UI Automation tree with Accessibility Insights for Windows or Inspect. - [ ] 使用 Accessibility Insights for Windows 或 Inspect 检查 UI Automation 树。
- [ ] Test light, dark, and at least one high-contrast theme. - [ ] 测试浅色、深色和至少一种高对比度主题。
- [ ] Measure text contrast and verify that color is not the only cue. - [ ] 测量文本对比度，并确认颜色不是唯一提示。
- [ ] Test Windows text-size changes, display scale changes, Magnifier, and narrow windows. - [ ] 测试 Windows 文本大小变化、显示缩放变化、放大镜和窄窗口。
- [ ] Test mouse, touch when supported, context menus, and alternatives to drag/hover. - [ ] 测试鼠标、支持时的触控、上下文菜单，以及拖拽/悬停的替代方式。
- [ ] Check long strings, localization expansion, and any supported right-to-left language. - [ ] 检查长字符串、本地化扩展和任何受支持的从右到左语言。
- [ ] Add automated accessibility checks for critical screens and flows where the test stack supports them. - [ ] 在测试技术栈支持时，为关键界面和流程添加自动化无障碍检查。
## 8. Official sources ## 8. 官方资料
- [Accessibility checklist for Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist) - [Windows 应用无障碍检查清单](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
- [Keyboard interactions](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions) - [键盘交互](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
- [Guidelines for touch targets](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting) - [触控目标指南](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
- [Touch interactions](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions) - [触控交互](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions)
- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements) - [无障碍文本要求](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
- [Accessibility testing](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing) - [无障碍测试](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing)
references/windows-foundations.md
+90 -90
View File
@@ -1,129 +1,129 @@
# Windows visual and layout foundations # Windows 视觉与布局基础
## Contents ## 目录
1. Design principles 1. 设计原则
2. Visual foundations 2. 视觉基础
3. Layout and responsive behavior 3. 布局与响应式行为
4. Color and themes 4. 颜色与主题
5. Materials and elevation 5. 材质与层级
6. Typography, icons, and motion 6. 字体、图标与动效
7. Foundation review checklist 7. 基础规范检查清单
8. Official sources 8. 官方资料
## 1. Design principles ## 1. 设计原则
Use the current Windows 11 principles as evaluation questions: 将当前 Windows 11 设计原则作为评估问题：
| Principle | Ask | | 原则 | 评估问题 |
|---|---| |---|---|
| Effortless | Can users complete the primary task with focus, precision, and little interpretation? | | Effortless（轻松） | 用户能否专注、准确且无需过多理解就完成主要任务？ |
| Calm | Is secondary chrome quiet enough for content and current work to dominate? | | Calm（平静） | 次要界面元素是否足够克制，让内容和当前工作占据主导？ |
| Personal | Does the app respect theme, accent, text size, input, and user preferences? | | Personal（个性化） | 应用是否尊重主题、强调色、文本大小、输入方式和用户偏好？ |
| Familiar | Do navigation, commands, selection, windowing, and feedback behave like Windows? | | Familiar（熟悉） | 导航、命令、选择、窗口化和反馈是否符合 Windows 行为？ |
| Complete + Coherent | Do screens, windows, states, and input modes feel like one system? | | Complete + Coherent（完整且一致） | 界面、窗口、状态和输入方式是否形成统一系统？ |
Do not substitute the older Fluent vocabulary of light, depth, motion, material, and scale for these five product principles. Treat color, elevation, iconography, materials, geometry, typography, and motion as visual foundations. 不要用早期 Fluent 中的 Light、Depth、Motion、Material 和 Scale 词汇替代这五项产品原则。将颜色、层级、图标、材质、几何、字体和动效视为视觉基础。
## 2. Visual foundations ## 2. 视觉基础
Build a semantic token layer instead of styling each screen independently: 建立语义化 Token 层，不要单独设置每个界面的样式：
- `surface.base`, `surface.layer`, `surface.overlay`; - `surface.base`、`surface.layer`、`surface.overlay`；
- `text.primary`, `text.secondary`, `text.disabled`; - `text.primary`、`text.secondary`、`text.disabled`；
- `accent.default`, `accent.hover`, `accent.pressed`, `accent.disabled`; - `accent.default`、`accent.hover`、`accent.pressed`、`accent.disabled`；
- `status.success`, `status.caution`, `status.critical`, `status.informational`; - `status.success`、`status.caution`、`status.critical`、`status.informational`；
- `stroke.control`, `stroke.divider`, `focus.stroke`; - `stroke.control`、`stroke.divider`、`focus.stroke`；
- `space.1` through `space.n`, `radius.control`, `radius.overlay`; - `space.1` 到 `space.n`、`radius.control`、`radius.overlay`；
- `motion.fast`, `motion.normal`, and shared easing tokens. - `motion.fast`、`motion.normal` 和共享缓动 Token。
Map these semantics to WinUI theme resources where available. Keep brand tokens above platform tokens so light, dark, and high-contrast mappings remain explicit. 在有对应资源时，将这些语义映射到 WinUI 主题资源。让品牌 Token 位于平台 Token 之上，明确浅色、深色和高对比度映射。
Use one primary accent action per local task area. Use size, spacing, alignment, and weight before adding more colors or surfaces. 每个局部任务区域只使用一个主要强调操作。先通过尺寸、间距、对齐和字重建立层级，再增加颜色或表面。
## 3. Layout and responsive behavior ## 3. 布局与响应式行为
Design in effective pixels (epx). Use multiples of 4 epx for sizes, margins, and positions when practical; text size is not restricted to this grid. 使用有效像素（epx）进行设计。尺寸、边距和位置在可行时使用 4 epx 的倍数；文本大小不受该网格限制。
Use the current Windows width classes as starting points, then adjust only when content demonstrates a real need: 以当前 Windows 宽度类别为起点，仅在内容证明有实际需要时调整：
| Class | Effective width | Typical response | | 类别 | 有效宽度 | 典型响应方式 |
|---|---:|---| |---|---:|---|
| Small | `<= 640` | single pane, collapsed or minimal navigation, stacked form, deferred secondary content | | 小 | `<= 640` | 单窗格、折叠或最小化导航、堆叠表单、延后显示次要内容 |
| Medium | `641–1007` | compact navigation, list/detail may switch between one and two panes | | 中 | `641–1007` | 紧凑导航、列表/详情可在单窗格和双窗格间切换 |
| Large | `>= 1008` | persistent navigation or multi-pane workspace when it improves the task | | 大 | `>= 1008` | 在有助于任务时使用常驻导航或多窗格工作区 |
Use the actual content region or window width, not monitor resolution. Validate at the app's supported minimum size, Windows Snap widths, restored windows, maximized windows, and across display scaling changes. 使用实际内容区域或窗口宽度，而不是显示器分辨率。在应用支持的最小尺寸、Windows 贴靠宽度、还原窗口、最大化窗口以及跨显示缩放变化时进行验证。
Apply responsive techniques deliberately: 有意识地应用响应式技术：
- **Reflow:** wrap or stack content without changing meaning. - **重排（Reflow）：** 在不改变含义的情况下换行或堆叠内容。
- **Resize:** let flexible regions absorb space; constrain readable text measure. - **调整大小（Resize）：** 让弹性区域吸收空间，并限制文本的可读行宽。
- **Reposition:** move secondary panels or commands while preserving order. - **重新定位（Reposition）：** 移动次要面板或命令，同时保持顺序。
- **Reveal:** progressively expose low-priority content as room grows. - **显示（Reveal）：** 随可用空间增加，逐步展示低优先级内容。
- **Replace:** switch to a more suitable navigation or presentation control. - **替换（Replace）：** 切换为更适合的导航或展示控件。
- **Re-architect:** use a different workflow only when a compact window cannot support the same structure. - **重构（Re-architect）：** 仅当紧凑窗口无法支持相同结构时改用不同工作流。
Define the narrow state as the safe default, then use `VisualStateManager` and `AdaptiveTrigger` for wider states. Prefer control-provided thresholds such as `NavigationView` compact/open pane widths when those express the intended behavior. Avoid fixed widths for content that must localize or scale. 将窄屏状态定义为安全默认状态，再使用 `VisualStateManager` 和 `AdaptiveTrigger` 添加宽屏状态。当 `NavigationView` 的紧凑/展开窗格宽度等控件阈值能表达预期行为时，优先使用这些阈值。避免给需要本地化或缩放的内容设置固定宽度。
## 4. Color and themes ## 4. 颜色与主题
- Use `{ThemeResource ...}` for colors and brushes that must update when the theme changes. - 对必须随主题运行时更新的颜色和画刷使用 `{ThemeResource ...}`。
- Test light, dark, and high contrast independently; do not generate dark mode by inversion. - 分别测试浅色、深色和高对比度；不要通过反相生成深色模式。
- Respect the system accent color unless product identity or domain semantics justify a controlled brand accent. - 尊重系统强调色，除非产品标识或领域语义足以证明需要受控的品牌强调色。
- Maintain at least 4.5:1 contrast for normal text. Use icons, text, or patterns in addition to semantic color. - 普通文本至少保持 4.5:1 对比度。除语义色外，同时使用图标、文本或图案。
- Do not encode state only through reduced opacity. Preserve recognizable text, focus, selection, and disabled semantics. - 不要只通过降低不透明度表达状态。保持文本、焦点、选择和禁用语义可辨认。
- Never place critical text over a material or image without a deterministic readable fallback. - 不要把关键文本放在无法确定可读性的材质或图像上，必须提供明确可读的回退方案。
Prefer system resources such as text fill, control fill, stroke, accent fill, and system status brushes. Verify resource names against the project's Windows App SDK version before emitting code. 优先使用文本填充、控件填充、描边、强调色填充和系统状态画刷等系统资源。生成代码前，根据项目的 Windows App SDK 版本验证资源名称。
## 5. Materials and elevation ## 5. 材质与层级
Use material to clarify layers, not to decorate every container: 使用材质来明确层级，不要装饰每个容器：
| Need | Preferred mechanism | Notes | | 需求 | 首选机制 | 说明 |
|---|---|---| |---|---|---|
| Main window background | `MicaBackdrop` | Windows 11; solid fallback on Windows 10 | | 主窗口背景 | `MicaBackdrop` | 用于 Windows 11；在 Windows 10 回退为纯色 |
| Desktop-see-through window | `DesktopAcrylicBackdrop` | More visually active; use only when the experience benefits | | 可透视桌面的窗口 | `DesktopAcrylicBackdrop` | 视觉更活跃；仅在体验确有收益时使用 |
| Material on a specific region | `SystemBackdropElement` | Requires Windows App SDK 1.6.3 or later | | 特定区域的材质 | `SystemBackdropElement` | 需要 Windows App SDK 1.6.3 或更高版本 |
| Blur content inside the window | in-app `AcrylicBrush` | Does not show the desktop behind the app | | 模糊窗口内部内容 | 应用内 `AcrylicBrush` | 不会显示应用背后的桌面 |
| Simple content surface | theme solid color | Often the clearest and cheapest choice | | 简单内容表面 | 主题纯色 | 通常是最清晰且成本最低的选择 |
Do not use UWP `HostBackdrop` patterns in WinUI 3. Allow system fallback when transparency is disabled, hardware is insufficient, Battery Saver suppresses Acrylic, Remote Desktop is active, or high contrast is enabled. Ensure the fallback color preserves hierarchy and contrast. 不要在 WinUI 3 中使用 UWP `HostBackdrop` 模式。透明效果关闭、硬件不足、节电模式抑制 Acrylic、使用远程桌面或启用高对比度时，允许系统自动回退。确保回退颜色仍能维持层级和对比度。
Use elevation only to communicate overlap, focus, or transient UI. Prefer system shadows and overlay behavior. Do not introduce an external shadow control merely to make cards look raised. 仅用层级表达重叠、焦点或临时 UI。优先使用系统阴影和覆盖层行为。不要仅为了让卡片显得凸起而引入外部阴影控件。
## 6. Typography, icons, and motion ## 6. 字体、图标与动效
Use Segoe UI Variable and the WinUI type ramp by default. Reuse platform text styles rather than copying numeric sizes throughout XAML. Use regular body weight, stronger titles or labels, tabular figures for aligned numeric data, and wrapping before truncation. When truncation is unavoidable, expose the full value through an accessible tooltip or detail surface. 默认使用 Segoe UI Variable 和 WinUI 字体层级。复用平台文本样式，不要在整个 XAML 中重复数值字号。正文使用常规字重，标题或标签使用更强字重，对齐的数字数据使用等宽数字，并优先换行而不是截断。无法避免截断时，通过无障碍工具提示或详情界面公开完整值。
Use `SymbolIcon`, `FontIcon` with Segoe Fluent Icons, or a consistent vector asset set. Keep icon metaphor, size, stroke/fill style, and alignment consistent. Give unfamiliar or icon-only commands an accessible name and tooltip. Do not use emoji as navigation or command icons. 使用 `SymbolIcon`、搭配 Segoe Fluent Icons 的 `FontIcon`，或一致的矢量资源集。保持图标隐喻、大小、描边/填充风格和对齐一致。为不熟悉或仅有图标的命令提供无障碍名称和工具提示。不要使用 Emoji 作为导航或命令图标。
Use motion to explain causality, hierarchy, and continuity: 使用动效解释因果关系、层级和连续性：
- give immediate pointer/press feedback; - 立即提供指针/按下反馈；
- prefer platform transitions and connected animations where they clarify movement; - 在有助于解释移动时，优先使用平台过渡和连接动画；
- animate compositor-friendly properties such as opacity and transforms; - 为不透明度和变换等适合合成器的属性设置动画；
- keep motion interruptible and never use it to delay input; - 保持动画可中断，绝不使用动画延迟输入；
- reduce or remove nonessential motion when system animation settings request it; - 当系统动画设置要求时，减少或移除非必要动效；
- avoid perpetual decorative movement in productivity surfaces. - 避免在生产力界面中使用持续循环的装饰性动效。
## 7. Foundation review checklist ## 7. 基础规范检查清单
- [ ] The UI reflects Effortless, Calm, Personal, Familiar, and Complete + Coherent. - [ ] UI 体现 Effortless、Calm、Personal、Familiar 和 Complete + Coherent。
- [ ] Semantic tokens cover themes and all interaction states. - [ ] 语义 Token 覆盖主题和所有交互状态。
- [ ] Layout is proven at compact, medium, wide, snapped, and scaled conditions. - [ ] 布局已在紧凑、中等、宽、贴靠和缩放条件下验证。
- [ ] Spacing and geometry follow a coherent 4 epx rhythm. - [ ] 间距和几何遵循一致的 4 epx 节奏。
- [ ] Material choice communicates a layer and has a solid fallback. - [ ] 材质选择能表达层级并具有纯色回退方案。
- [ ] Typography remains readable under text scaling and localization. - [ ] 字体在文本缩放和本地化后仍可读。
- [ ] Icons use one language and are not emoji. - [ ] 图标采用统一语言且不使用 Emoji。
- [ ] Motion communicates change and respects user settings. - [ ] 动效能传达变化并尊重用户设置。
## 8. Official sources ## 8. 官方资料
- [Windows design principles](https://learn.microsoft.com/windows/apps/design/design-principles) - [Windows 设计原则](https://learn.microsoft.com/windows/apps/design/design-principles)
- [Windows design guidelines](https://learn.microsoft.com/windows/apps/design/guidelines-overview) - [Windows 设计指南](https://learn.microsoft.com/windows/apps/design/guidelines-overview)
- [Screen sizes and breakpoints](https://learn.microsoft.com/windows/apps/design/layout/screen-sizes-and-breakpoints-for-responsive-design) - [屏幕尺寸与断点](https://learn.microsoft.com/windows/apps/design/layout/screen-sizes-and-breakpoints-for-responsive-design)
- [Content layout and spacing](https://learn.microsoft.com/windows/apps/design/basics/content-basics) - [内容布局与间距](https://learn.microsoft.com/windows/apps/design/basics/content-basics)
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials) - [Windows 应用中的材质](https://learn.microsoft.com/windows/apps/develop/ui/materials)
- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements) - [无障碍文本要求](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)