winui-design

Search samples before writing XAML

This skill ships winui-search.exe alongside this SKILL.md (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, 90+ Reactor declarative-C# controls, curated platform-integration patterns; each result returns full code — XAML + C#, or C#-only for Reactor — plus pitfall notes). Front-load lookups, then code — don't interleave.

.\winui-search.exe search "<feature 1>" "<feature 2>" ...   # batch one focused query per feature (BM25 likes focused phrasing)
.\winui-search.exe get <id 1> <id 2> ...                     # batch up to 3 IDs — full XAML + C# + pitfall notes

Search covers controls and platform integration (file pickers, Share, JumpList, drag-drop, app lifecycle, dialogs) — front-load all lookups before writing XAML; don't interleave search with coding.

App-shape anchors

Pick the closest shipping app silhouette before laying out a page:

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 → GridView or ItemsRepeater + UniformGridLayout; hierarchy → TreeView; tabular → ListView with a Grid-based ItemTemplate and a header Grid above (WinUI has no DataGrid; don't default to CommunityToolkit.WinUI.Controls.DataGrid — its columns can't use x:Bind); master-detail → ListView + detail Grid.
• 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, search winui-search.exe 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 in MainWindow'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:

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

TextBox two-way needs 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.

Attached properties from C# use static setters, not initializers

Converter={x:Null} crashes x:Bind at runtime

{x:Bind} requires Converter to be a {StaticResource} lookup. Converter={x:Null} compiles but the generated code calls LookupConverter(""), which returns null, then dereferences it — you get Resource Dictionary Key can only be String-typed / NullReferenceException on first activation of the binding. If you don't want a converter, omit the property entirely.

Prefer x:Bind static functions over IValueConverter

Acrylic and ThemeShadow rendering rules

• BackgroundSizing defaults to InnerBorderEdge on both Border and Control, which correctly clips acrylic to the inner stroke. The hazard is the opposite of intuition: don't change it to OuterBorderEdge on a bordered acrylic surface — that's what makes the material bleed past the stroke.
• ThemeShadow casts a shadow from the caster's Translation Z. Microsoft's recommended elevations are 16 for tooltips, 32 for popup/flyout UI, 128 for dialogs — pick by surface type. For non-popup casters, add the surfaces it should land on to ThemeShadow.Receivers; otherwise the shadow has nothing to fall on and looks clipped.

Theming rules (short version)

• {ThemeResource ...} at usage sites (updates on theme switch). {StaticResource} inside ThemeDictionaries for theme-local definitions; SystemAccentColor / SystemColor* are the exceptions and stay {ThemeResource}.
• Custom theme dictionaries cover Light, Dark, and HighContrast explicitly — never Default.
• Name resources by purpose (CardBackgroundBrush, DangerTextBrush), not hue.
• Light/Dark working ≠ High Contrast working. Test in a Contrast theme separately.
• Never set HighContrastAdjustment="None" unless your app already supplies system-aware brushes throughout.

Anti-patterns

Build custom UI only when all are true: no platform/Gallery/Toolkit control fits; you'll implement keyboard, focus, UI Automation, theme resources, High Contrast, and responsive behaviour; you have specs for default/hover/pressed/disabled/selected/focused/error states; you've tested with keyboard and a contrast theme.

References (load on demand)