{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"winui3","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'WinUI 3 and Windows App SDK coding guidelines. Prevents common UWP API misuse, enforces correct XAML namespaces, threading, windowing, and MVVM patterns for desktop Windows apps.'\napplyTo: '**/*.xaml, **/*.cs, **/*.csproj'\n---\n\n# WinUI 3 / Windows App SDK\n\n## Critical Rules — NEVER Use Legacy UWP APIs\n\nThese UWP patterns are **wrong** for WinUI 3 desktop apps. Always use the Windows App SDK equivalent.\n\n- **NEVER** use `Windows.UI.Popups.MessageDialog`. Use `ContentDialog` with `XamlRoot` set.\n- **NEVER** show a `ContentDialog` without setting `dialog.XamlRoot = this.Content.XamlRoot` first.\n- **NEVER** use `CoreDispatcher.RunAsync` or `Dispatcher.RunAsync`. Use `DispatcherQueue.TryEnqueue`.\n- **NEVER** use `Window.Current`. Track the main window via a static `App.MainWindow` property.\n- **NEVER** use `Windows.UI.Xaml.*` namespaces. Use `Microsoft.UI.Xaml.*`.\n- **NEVER** use `Windows.UI.Composition`. Use `Microsoft.UI.Composition`.\n- **NEVER** use `Windows.UI.Colors`. Use `Microsoft.UI.Colors`.\n- **NEVER** use `ApplicationView` or `CoreWindow` for window management. Use `Microsoft.UI.Windowing.AppWindow`.\n- **NEVER** use `CoreApplicationViewTitleBar`. Use `AppWindowTitleBar`.\n- **NEVER** use `GetForCurrentView()` patterns (e.g., `UIViewSettings.GetForCurrentView()`). These do not exist in desktop WinUI 3. Use `AppWindow` APIs instead.\n- **NEVER** use UWP `PrintManager` directly. Use `IPrintManagerInterop` with a window handle.\n- **NEVER** use `DataTransferManager` directly for sharing. Use `IDataTransferManagerInterop` with a window handle.\n- **NEVER** use UWP `IBackgroundTask`. Use `Microsoft.Windows.AppLifecycle` activation.\n- **NEVER** use `WebAuthenticationBroker`. Use `OAuth2Manager` (Windows App SDK 1.7+).\n\n## XAML Patterns\n\n- The default XAML namespace maps to `Microsoft.UI.Xaml`, not `Windows.UI.Xaml`.\n- Prefer `{x:Bind}` over `{Binding}` for compiled, type-safe, higher-performance bindings.\n- Set `x:DataType` on `DataTemplate` elements when using `{x:Bind}` — this is required for compiled bindings in templates. On Page/UserControl, `x:DataType` enables compile-time binding validation but is not strictly required if the DataContext does not change.\n- Use `Mode=OneWay` for dynamic values, `Mode=OneTime` for static, `Mode=TwoWay` only for editable inputs.\n- Do not bind static constants — set them directly in XAML.\n\n## Threading\n\n- Use `DispatcherQueue.TryEnqueue(() =\u003e { ... })` to update UI from background threads.\n- `TryEnqueue` returns `bool`, not a `Task` — it is fire-and-forget.\n- Check thread access with `DispatcherQueue.HasThreadAccess` before dispatching.\n- WinUI 3 uses standard STA (not ASTA). No built-in reentrancy protection — be cautious with async code that pumps messages.\n\n## Windowing\n\n- Get the `AppWindow` from a WinUI 3 `Window` via `WindowNative.GetWindowHandle` → `Win32Interop.GetWindowIdFromWindow` → `AppWindow.GetFromWindowId`.\n- Use `AppWindow` for resize, move, title, and presenter operations.\n- Custom title bar: use `AppWindow.TitleBar` properties, not `CoreApplicationViewTitleBar`.\n- Track the main window as `App.MainWindow` (a static property set in `OnLaunched`).\n\n## Dialogs and Pickers\n\n- **ContentDialog**: Always set `dialog.XamlRoot = this.Content.XamlRoot` before calling `ShowAsync()`.\n- **File/Folder Pickers**: Initialize with `WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd)` where `hwnd` comes from `WindowNative.GetWindowHandle(App.MainWindow)`.\n- **Share/Print**: Use COM interop interfaces (`IDataTransferManagerInterop`, `IPrintManagerInterop`) with window handles.\n\n## MVVM and Data Binding\n\n- Prefer `CommunityToolkit.Mvvm` (`[ObservableProperty]`, `[RelayCommand]`) for MVVM infrastructure.\n- Use `Microsoft.Extensions.DependencyInjection` for service registration and injection.\n- Keep UI (Views) focused on layout and bindings; keep logic in ViewModels and services.\n- Use `async`/`await` for I/O and long-running work to keep the UI responsive.\n\n## Project Setup\n\n- Target `net10.0-windows10.0.22621.0` (or appropriate TFM for the project's target SDK).\n- Set `\u003cUseWinUI\u003etrue\u003c/UseWinUI\u003e` in the project file.\n- Reference the latest stable `Microsoft.WindowsAppSDK` NuGet package.\n- Use `System.Text.Json` with source generators for JSON serialization.\n\n## C# Code Style\n\n- Use file-scoped namespaces.\n- Enable nullable reference types. Use `is null` / `is not null` instead of `== null`.\n- Prefer pattern matching over `as`/`is` with null checks.\n- PascalCase for types, methods, properties. camelCase for private fields.\n- Allman brace style (opening brace on its own line).\n- Prefer explicit types for built-in types; use `var` only when the type is obvious.\n\n## Accessibility\n\n- Set `AutomationProperties.Name` on all interactive controls.\n- Use `AutomationProperties.HeadingLevel` on section headers.\n- Hide decorative elements with `AutomationProperties.AccessibilityView=\"Raw\"`.\n- Ensure full keyboard navigation (Tab, Enter, Space, arrow keys).\n- Meet WCAG color contrast requirements.\n\n## Performance\n\n- Prefer `{x:Bind}` (compiled) over `{Binding}` (reflection-based).\n- **NativeAOT:** Under Native AOT compilation, `{Binding}` (reflection-based) does not work at all. Only `{x:Bind}` (compiled bindings) is supported. If the project uses NativeAOT, use `{x:Bind}` exclusively.\n- Use `x:Load` or `x:DeferLoadStrategy` for UI elements that are not immediately needed.\n- Use `ItemsRepeater` with virtualization for large lists.\n- Avoid deep layout nesting — prefer `Grid` over nested `StackPanel` chains.\n- Use `async`/`await` for all I/O; never block the UI thread.\n\n## App Settings (Packaged vs Unpackaged)\n\n- **Packaged apps**: `ApplicationData.Current.LocalSettings` works as expected.\n- **Unpackaged apps**: Use a custom settings file (e.g., JSON in `Environment.GetFolderPath(SpecialFolder.LocalApplicationData)`).\n- Do not assume `ApplicationData` is always available — check packaging status first.\n\n## Typography\n\n- **Always** use built-in TextBlock styles (`CaptionTextBlockStyle`, `BodyTextBlockStyle`, `BodyStrongTextBlockStyle`, `SubtitleTextBlockStyle`, `TitleTextBlockStyle`, `TitleLargeTextBlockStyle`, `DisplayTextBlockStyle`).\n- Prefer using the built-in TextBlock styles over hardcoding `FontSize`, `FontWeight`, or `FontFamily`.\n- Font: Segoe UI Variable is the default — do not change it.\n- Use sentence casing for all UI text.\n\n\n## Theming \u0026 Colors\n\n- **Always** use `{ThemeResource}` for brushes and colors to support Light, Dark, and High Contrast themes automatically.\n- **Never** hardcode color values (`#FFFFFF`, `Colors.White`, etc.) for UI elements. Use theme resources like `TextFillColorPrimaryBrush`, `CardBackgroundFillColorDefaultBrush`, `CardStrokeColorDefaultBrush`.\n- Use `SystemAccentColor` (and `Light1`–`Light3`, `Dark1`–`Dark3` variants) for the user's accent color palette.\n- For borders: use `CardStrokeColorDefaultBrush` or `ControlStrokeColorDefaultBrush`.\n\n## Spacing \u0026 Layout\n\n- Use a **4px grid system**: all margins, padding, and spacing values must be multiples of 4px.\n- Standard spacing: 4 (compact), 8 (controls), 12 (small gutters), 16 (content padding), 24 (large gutters).\n- Prefer `Grid` over deeply nested `StackPanel` chains for performance.\n- Use `Auto` for content-sized rows/columns, `*` for proportional sizing. Avoid fixed pixel sizes.\n- Use `VisualStateManager` with `AdaptiveTrigger` for responsive layouts at breakpoints (640px, 1008px).\n- Use `ControlCornerRadius` (4px) for small controls and `OverlayCornerRadius` (8px) for cards, dialogs, flyouts.\n\n## Materials \u0026 Elevation\n\n- Use **Mica** (`MicaBackdrop`) for the app window backdrop. Requires transparent layers above to show through.\n- Use **Acrylic** for transient surfaces only (flyouts, menus, navigation panes).\n- Use `LayerFillColorDefaultBrush` for content layers above Mica.\n- Use `ThemeShadow` with Z-axis `Translation` for elevation. Cards: 4–8 px, Flyouts: 32 px, Dialogs: 128 px.\n\n## Motion \u0026 Transitions\n\n- Use built-in theme transitions (`EntranceThemeTransition`, `RepositionThemeTransition`, `ContentThemeTransition`, `AddDeleteThemeTransition`).\n- Avoid custom storyboard animations when a built-in transition exists.\n\n## Control Selection\n\n- Use `NavigationView` for primary app navigation (not custom sidebars).\n- Use `InfoBar` for persistent in-app notifications (not custom banners).\n- Use `TeachingTip` for contextual guidance (not custom popups).\n- Use `NumberBox` for numeric input (not TextBox with manual validation).\n- Use `ToggleSwitch` for on/off settings (not CheckBox).\n- Use `ItemsView` as the modern collection control for displaying data with built-in selection, virtualization, and layout flexibility.\n- Use `ListView`/`GridView` for standard virtualized lists and grids, especially when built-in selection support is needed.\n- Use `ItemsRepeater` only for fully custom virtualizing layouts where you need complete control over rendering and do not need built-in selection or interaction handling.\n- Use `Expander` for collapsible sections (not custom visibility toggling).\n\n## Error Handling\n\n- Always wrap `async void` event handlers in try/catch to prevent unhandled crashes.\n- Use `InfoBar` (with `Severity = Error`) for user-facing error messages, not `ContentDialog` for routine errors.\n- Handle `App.UnhandledException` for logging and graceful recovery.\n\n## Testing\n\n- **NEVER** use a plain MSTest or xUnit project for tests that instantiate WinUI 3 XAML types. Use a **Unit Test App (WinUI in Desktop)** project, which provides the Xaml runtime and UI thread.\n- Use `[TestMethod]` for pure logic tests. Use `[UITestMethod]` for any test that creates or interacts with `Microsoft.UI.Xaml` types (controls, pages, user controls).\n- Place testable business logic in a **Class Library (WinUI in Desktop)** project, separate from the main app.\n- Build the solution before running tests to enable Visual Studio test discovery.\n\n## Resources \u0026 Localization\n\n- Store user-facing strings in `Resources.resw` files, not in code or XAML literals.\n- Use `x:Uid` in XAML for localized text binding.\n- Use DPI-qualified image assets (`logo.scale-200.png`); reference without scale qualifier (`ms-appx:///Assets/logo.png`).\n","description":"WinUI 3 and Windows App SDK coding guidelines. Prevents common UWP API misuse, enforces correct XAML namespaces, threading, windowing, and MVVM patterns for desktop Windows apps.","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/winui3.instructions.md"},"manifest":{}},"content_hash":[241,192,229,6,120,223,242,242,94,247,235,185,135,241,87,91,228,184,182,79,110,10,71,55,158,159,59,144,194,15,41,175],"trust_level":"unsigned","yanked":false}