winui
The winui Claude Code skill guides developers through building and reviewing WinUI 3 applications using the Windows App SDK. Use it when creating native modern Windows desktop UI, integrating Windows App SDK features into .NET applications, deciding between Windows UI frameworks, or implementing MVVM patterns. The skill handles packaging decisions, navigation architecture, theming, windowing, and interoperability boundaries across .NET stacks.
git clone --depth 1 https://github.com/managedcode/dotnet-skills /tmp/winui && cp -r /tmp/winui/catalog/Frameworks/WinUI/skills/winui ~/.claude/skills/winuiSKILL.md
# WinUI 3 and Windows App SDK
## Trigger On
- building native modern Windows desktop UI on WinUI 3
- integrating Windows App SDK features into a .NET app
- deciding between WinUI, WPF, WinForms, and MAUI for Windows work
- implementing MVVM patterns in Windows App SDK applications
## Workflow
1. **Confirm WinUI is the right choice** — use when modern Windows-native UI, Fluent Design, and Windows App SDK capabilities are needed. For cross-platform, consider MAUI instead.
2. **Choose packaging model early** — packaged (MSIX) vs unpackaged differ materially for deployment, identity, and API access:
```xml
<!-- Unpackaged: add to .csproj -->
<WindowsPackageType>None</WindowsPackageType>
```
3. **Apply MVVM pattern** with the MVVM Toolkit — keep views dumb, logic in ViewModels:
```csharp
public partial class ProductsViewModel : ObservableObject
{
[ObservableProperty]
private ObservableCollection<Product> _products = [];
[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(DeleteCommand))]
private Product? _selectedProduct;
[RelayCommand(CanExecute = nameof(CanDelete))]
private async Task DeleteAsync()
{
if (SelectedProduct is null) return;
await _productService.DeleteAsync(SelectedProduct.Id);
Products.Remove(SelectedProduct);
}
private bool CanDelete() => SelectedProduct is not null;
}
```
4. **Use x:Bind for compiled bindings** — better performance and compile-time checking than `{Binding}`:
```xml
<TextBlock Text="{x:Bind ViewModel.Title, Mode=OneWay}"/>
```
5. **Wire DI through `Host.CreateDefaultBuilder`** — register services, ViewModels, and views. Resolve via `App.GetService<T>()`.
6. **Implement navigation service** — map ViewModels to Pages by convention. See [references/patterns.md](references/patterns.md) for the full pattern.
7. **Handle Windows App SDK features** — windowing (AppWindow), custom title bar, app lifecycle, notifications.
8. **Always set `XamlRoot`** when showing ContentDialog — omitting this causes silent failures.
9. **Validate on Windows targets** — behavior depends on runtime, packaging model, and Windows version.
```mermaid
flowchart LR
A["Choose WinUI"] --> B["Select packaging model"]
B --> C["MVVM + DI setup"]
C --> D["Navigation and views"]
D --> E["Windows App SDK features"]
E --> F["Validate on target runtime"]
```
## Key Decisions
| Decision | Guidance |
|----------|----------|
| Packaged vs unpackaged | Packaged (MSIX) for Store, auto-update, and full API access; unpackaged for simpler deployment |
| x:Bind vs Binding | Always prefer x:Bind — compiled, faster, type-safe |
| MVVM Toolkit attributes | Use `[ObservableProperty]`, `[RelayCommand]` to eliminate boilerplate |
| Navigation | Convention-based ViewModel→Page mapping via navigation service |
| Theming | Use `RequestedTheme` on root element; respect system theme by default |
## Deliver
- modern Windows UI code with clear platform boundaries
- explicit deployment and packaging assumptions
- MVVM pattern with testable ViewModels
- cleaner interop between shared and Windows-specific layers
## Validate
- WinUI is chosen for a real product reason, not defaulted to
- Windows App SDK dependencies are explicit in the project file
- packaging and runtime assumptions are tested on target
- x:Bind is used for compiled bindings throughout
- navigation and ContentDialog both work with correct XamlRoot
- custom title bar renders correctly on Windows 10 and 11
## References
- [references/patterns.md](references/patterns.md) - WinUI 3 patterns including MVVM, navigation services, DI setup, windowing, theming, dialogs, and lifecycle handling
- [references/anti-patterns.md](references/anti-patterns.md) - common WinUI mistakes with explanations and correctionsBuild, debug, modernize, or review ASP.NET Core applications with correct hosting, middleware, security, configuration, logging, and deployment patterns on current .NET. USE FOR: working on ASP.NET Core apps, services, or middleware; changing auth, routing, configuration, hosting, or deployment behavior; deciding between ASP.NET Core sub-stacks. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Build, upgrade, and operate .NET Aspire 13.3.x application hosts with current CLI, AppHost, ServiceDefaults, integrations, dashboard, testing, and Azure deployment patterns for distributed apps. USE FOR: Aspire.AppHost.Sdk, Aspire.Hosting.*, DistributedApplication.CreateBuilder, WithReference, WaitFor, AddProject, AddRedis, AddPostgres, aspire run, aspire init, aspire. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Build, review, or migrate Azure Functions in .NET with correct execution model, isolated worker setup, bindings, DI, and Durable Functions patterns. USE FOR: working on Azure Functions in .NET; migrating from the in-process model to the isolated worker model; adding Durable Functions, bindings, or host configuration. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Build and review Blazor applications across server, WebAssembly, web app, and hybrid scenarios with correct component design, state flow, rendering, and hosting choices. USE FOR: building interactive web UIs with C# instead of JavaScript; choosing between Server, WebAssembly, or Auto render modes; designing component hierarchies and state. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Maintain or migrate EF6-based applications with realistic guidance on what to keep, what to modernize, and when EF Core is or is not the right next step. USE FOR: EF6 codebases; runtime versus ORM migration decisions; EDMX, code-first, ObjectContext, and legacy data-access review. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Design, tune, or review EF Core data access with proper modeling, migrations, query translation, performance, and lifetime management for modern .NET applications. USE FOR: DbContext, migrations, model configuration, EF queries, tracking, loading, performance, transactions, and EF6 migration decisions. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Build, review, or migrate .NET MAUI applications across Android, iOS, macOS, and Windows with correct cross-platform UI, platform integration, and native packaging assumptions. USE FOR: working on cross-platform mobile or desktop UI in .NET MAUI; integrating device capabilities, navigation, or platform-specific code; migrating Xamarin.Forms or aligning. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
Use ML.NET to train, evaluate, or integrate machine-learning models into .NET applications with realistic data preparation, inference, and deployment expectations. USE FOR: ML.NET integration; local model training or retraining; inference pipelines, model loading, evaluation, and deployment review. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.