references/engineering-validation.md

# WinUI engineering and validation

## Contents

1. Version and dependency gates
2. XAML and state architecture
3. Windowing and responsive implementation
4. Performance and async behavior
5. Implementation review
6. Release test matrix
7. Severity model
8. Official sources

## 1. Version and dependency gates

Before generating XAML or C#:

1. Read the project file, central package props, target framework, target/min Windows versions, and installed packages.
2. Identify the Windows App SDK and Windows Community Toolkit versions exactly.
3. Check whether the project is packaged or unpackaged and whether it uses single-project MSIX.
4. Verify the proposed API in current Microsoft documentation and, for controls, the WinUI 3 Gallery.
5. Record minimum-version and fallback behavior in the recommendation.

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.

Examples of version-sensitive guidance:

- the WinUI `TitleBar` control requires Windows App SDK 1.7 or later;
- `SystemBackdropElement` requires Windows App SDK 1.6.3 or later;
- Mica requires Windows 11 and falls back to a solid theme surface on Windows 10;
- Windows Community Toolkit `DataGrid` is archived and not a WCT 8+ WinUI 3 control.

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.

## 2. XAML and state architecture

- Follow the project's MVVM or code-behind conventions; do not introduce a second architecture for one screen.
- 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.
- Put light, dark, and high-contrast mappings in theme dictionaries when custom tokens are necessary.
- 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.
- Use Grid and flexible sizing for structured layouts; avoid deep nested panels and fixed sizes that break localization or text scaling.
- Keep visual order aligned with reading and tab order.

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.

## 3. Windowing and responsive implementation

### 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.

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.

### 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.

## 4. Performance and async behavior

- Keep collection virtualization enabled and measure with realistic data, images, templates, and grouping.
- Prefer `ListView`, `GridView`, or `ItemsView` behavior before low-level `ItemsRepeater` customization.
- 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.
- 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.
- 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

Check correctness before visual polish:

- [ ] Namespace, APIs, package versions, and minimum OS are valid.
- [ ] 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.
- [ ] 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

Test representative combinations rather than one happy-path machine:

| Dimension | Minimum coverage |
|---|---|
| Windows | minimum supported OS plus current Windows 11 |
| Window | supported minimum, small `<=640` epx, medium `641–1007`, large `>=1008`, snapped, maximized |
| Scale | common 100%, 125%, 150%, 200% display scales and monitor transitions |
| Text | default and increased Windows text size |
| Theme | light, dark, high contrast; transparency on and off |
| Input | keyboard only, mouse, touch/pen when claimed |
| Assistive tech | Narrator, Magnifier, 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 |
| 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.

## 7. Severity model

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 |
| 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 |
| 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

- [WinUI 3 overview](https://learn.microsoft.com/windows/apps/winui/winui3/)
- [Title bar customization](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)
- [Responsive layouts with 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)
- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
- [Accessibility checklist](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)