winui-design
Use when designing, reviewing, or fixing WinUI 3: sample and control discovery with winapp find-ui, layout planning, control choice, Fluent Design alignment, Light/Dark/High Contrast theming, typography, spacing, brushes, accessibility, and XAML data-binding design. Load before authoring new XAML, reviewing UI PRs, migrating desktop UI to WinUI, or choosing between WinUI controls/patterns. Also use when asked to search WinUI samples, find a WinUI Gallery or Community Toolkit example, or find a control that does something.
microsoft · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add microsoft/win-dev-skills --skill winui-designAbout this skill
name: winui-design description: "Use when designing, reviewing, or fixing WinUI 3: sample and control discovery with winapp find-ui, layout planning, control choice, Fluent Design alignment, Light/Dark/High Contrast theming, typography, spacing, brushes, accessibility, and XAML data-binding design. Load before authoring new XAML, reviewing UI PRs, migrating desktop UI to WinUI, or choosing between WinUI controls/patterns. Also use when asked to search WinUI samples, find a WinUI Gallery or Community Toolkit example, or find a control that does something."
Search samples before writing XAML
WinApp CLI 0.6+ provides grounded control and sample discovery through winapp find-ui. Front-load lookups, then code:
winapp find-ui "<focused feature>" # compact matches + scenario IDs
winapp find-ui --id <scenario-id> # full XAML/C# + prerequisite notes
winapp find-ui --id <id-1> --id <id-2> --json # batch, structured output
winapp find-ui --list # browse all default-source scenarios
winapp find-ui "<feature>" --refresh # force a corpus refresh
Default search covers the WinUI Gallery, Windows Community Toolkit, and curated core patterns. Reactor's C#-only/MVU samples are opt-in with --source reactor; use them only for Reactor projects. The Gallery/Toolkit/Reactor corpus is fetched and cached by WinApp CLI, while core patterns work offline.
App-shape anchors
Pick the closest shipping app silhouette before laying out a page:
| App type | Anchor controls | Reference apps |
|---|---|---|
| Settings / config tool | NavigationView Left + SettingsCard / SettingsExpander | Windows Settings, Slack |
| Document / session editor | TabView + full-bleed content, light chrome | Windows Terminal, VS Code, Notepad |
| Hierarchical browser | TreeView + ListView + BreadcrumbBar | File Explorer, Outlook |
| Developer tool / dashboard | NavigationView + card layout | Dev Home, GitHub Desktop |
| Single-purpose utility | Mode switcher + compact grid | Calculator, Snipping Tool |
| Media / canvas / hero | Grid with hero surface, floating commands, no NavigationView | Photos, Spotify, Clipchamp |
Reach-for-this control map
Before writing XAML, map the requirement to a platform control. These mappings exist to short-circuit cross-framework instincts (WPF DataGrid, web <select>, HTML <input type=date>):
- Navigation: 2–7 sections →
NavigationView; document/session tabs →TabView; breadcrumb trail →BreadcrumbBar; 2–3 modes →SelectorBar. - Data display: Vertical list →
ListView; tiles/grid →GridVieworItemsRepeater+UniformGridLayout; hierarchy →TreeView; tabular →ListViewwith aGrid-basedItemTemplateand a headerGridabove (WinUI has noDataGrid; don't default toCommunityToolkit.WinUI.Controls.DataGrid— its columns can't usex:Bind); master-detail →ListView+ detailGrid. - Input: Text →
TextBox; number →NumberBox; search →AutoSuggestBox; date →CalendarDatePicker; boolean →ToggleSwitch; pick one from 2–3 →RadioButtons; pick one from 4+ →ComboBox. - Feedback: Blocking decision →
ContentDialog; contextual action →Flyout/MenuFlyout; onboarding / hint →TeachingTip; inline status / async progress →InfoBar; system notification →AppNotification.
If the mapping above doesn't fit, run winapp find-ui "<intent>" before improvising.
Window sizing (WinUI 3 specifics)
WinUI 3 has no
SizeToContent. Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. Size it inMainWindow's constructor.
Rubric. Width = widest row + 48 padding, rounded up to nearest 20. Height = 32 (titlebar) + Σ(row heights) + Σ(spacing) + 48 padding, rounded up to 20. Round up — clipped content is a worse failure than a slightly-wide window. Sanity ranges (derive yours from the rubric):
- Single-purpose utility → ~440–560 wide
- Form / single-page tool → ~600–800 wide, ~640–800 tall
- Multi-pane (nav + content) → ~1100–1300 wide, ~720–840 tall
- Document / canvas / media editor → 1280+ wide
AppWindow.Resize takes physical pixels, not DIPs — multiply by the monitor's DPI scale. XamlRoot.RasterizationScale is null in the constructor and stale after AppWindow.Move, so [DllImport] GetDpiForWindow is the cleanest path:
using Microsoft.UI;
using Microsoft.UI.Windowing;
using System.Runtime.InteropServices;
using Windows.Graphics;
public sealed partial class MainWindow : Window
{
[DllImport("user32.dll")]
private static extern uint GetDpiForWindow(IntPtr hWnd);
public MainWindow()
{
InitializeComponent();
var hwnd = Win32Interop.GetWindowFromWindowId(AppWindow.Id);
var scale = GetDpiForWindow(hwnd) / 96.0;
// widthDip / heightDip come from the rubric above — derive, don't copy.
AppWindow.Resize(new SizeInt32((int)(widthDip * scale), (int)(heightDip * scale)));
}
}
Don't size the window by setting Width/Height on the root Grid — that clips content, not the window.
XAML landmines (the things you'll otherwise ship broken)
x:Bind defaults to OneTime
<!-- ❌ silently never updates -->
<TextBlock Text="{x:Bind Vm.Status}" />
<!-- ✅ -->
<TextBlock Text="{x:Bind Vm.Status, Mode=OneWay}" />
TextBox two-way needs UpdateSourceTrigger=PropertyChanged
<TextBox Text="{x:Bind Vm.Name, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}" />
Default trigger resolves to LostFocus specifically for TextBox.Text (most other properties default to PropertyChanged). The VM is not updated per keystroke, and UIA keyboard-simulation tests (WinAppDriver SendKeys, etc.) that assert immediately after typing will see stale VM state until focus moves.