winui-xaml

name: winui-xaml description: "WinUI 3 and XAML best practices for layout, binding, async operations, collections, rendering, memory management, accessibility, and localization. Use when: (1) Working with WinUI 3 or Uno Platform XAML, (2) Optimizing UI performance, (3) Implementing data binding with x:Bind, (4) Managing collections and virtualization, (5) Ensuring accessibility compliance, (6) Handling async operations on UI thread, (7) Preventing memory leaks, (8) Implementing localization. Do NOT use for: C# Markup (see uno-csharp-markup) or Uno Toolkit controls (see uno-toolkit)." intent: >- Apply WinUI 3 and XAML best practices for layout, binding, async, collections, rendering, memory, accessibility, and localization. best_for: - "Optimizing XAML layout and rendering performance" - "Implementing accessible UI controls" - "Working with collections and virtualization" license: "CC-BY-4.0 (patterns derived from Microsoft Learn documentation)" metadata: version: "1.0.0"

WinUI 3 XAML Best Practices

Twelve categories of XAML best practices validated against WinUI 3 and Uno Platform, covering performance-critical patterns through polish optimizations.

Quick Reference - Top 10 Rules

1. Never block the UI thread - Use async/await for all I/O and long operations
2. Use x:Bind over Binding - Compile-time validation, 3x faster
3. Use x:Load for conditional UI - Prevents element creation until needed
4. Enable virtualization - ListView/ItemsRepeater for any list > 20 items
5. Unsubscribe event handlers - Clean up in Unloaded to prevent leaks
6. Keep visual tree shallow - Minimize nesting depth
7. Use OneTime mode for static data - Avoid unnecessary change tracking
8. Set AutomationProperties - Required for accessibility compliance
9. Use x:Uid for all user-visible text - Enables localization
10. Prefer Grid over nested StackPanels - Single layout pass vs multiple

Categories by Impact

Impact Levels

• CRITICAL: Can cause app crashes, multi-second freezes, or memory leaks
• HIGH: Noticeable performance degradation (100ms+)
• MEDIUM-HIGH: Cumulative impact across many elements
• MEDIUM: Optimization for polish and responsiveness

Pattern Structure

Each reference file follows this format:

### Skill Name
**Rule**: Concise imperative statement
**Why**: Technical rationale with measurable impact
**Example (XAML/C#)**: Correct implementation
**Common Mistakes**: Anti-patterns to avoid
**Uno Platform Notes**: Platform-specific gaps/workarounds (if applicable)
**Reference**: Microsoft Learn link

WinUI 3 vs UWP Key Differences

Uno Platform Compatibility

All patterns validated against Uno Platform with notes for:

• Platform-specific behavior differences
• Unsupported APIs and alternatives
• Skia renderer considerations

Common Mistakes

• Blocking the UI thread with .Result or .Wait() instead of async/await
• Using {Binding} instead of {x:Bind} (3x slower, no compile-time validation)
• Nesting StackPanels deeply instead of using Grid (multiple layout passes vs one)
• Forgetting to unsubscribe event handlers in Unloaded, causing memory leaks
• Using ListView without virtualization for large lists (>20 items)

Related Skills

Using References

Consult the individual reference files listed in the table above, matched to the task at hand. Each file is self-contained with rules, code examples, common mistakes, and Uno Platform compatibility notes.