Winui Design

UI Planning

Before picking controls, search the catalogue. This skill ships winui-search.exe alongside this SKILL.md. It indexes 100+ WinUI Gallery controls, every Windows Community Toolkit scenario, and a curated set of platform integration patterns (JumpList, Share, file pickers, drag-drop). Use it to ground every control choice in a real shipping sample before writing any XAML — this is the difference between guessing property names and copying canonical code.

>

```powershell

.\winui-search.exe search "<feature 1>" "<feature 2>" ... # batch one focused query per feature

.\winui-search.exe get <id 1> <id 2> ... # batch up to 3 IDs — full XAML + C# + pitfall notes

.\winui-search.exe list # browse all patterns (heavy — prefer search)

.\winui-search.exe update # force refresh now

```

>

Workflow: in one search call, list every feature you need for the current page (one focused query per feature, not a bag of keywords) → from each shortlist pick the best ID → grab full code with get (batch up to 3 IDs per call) → then write XAML using those samples as reference. Do NOT interleave searching with coding — front-load all lookups, then code. BM25 rewards focused per-query phrasing, so keep each query about one control or pattern.

Step 1: Identify App Type and Anchor Control

Step 2: Map Requirements to Controls

Navigation: 2-7 sections → NavigationView; document 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 Grid column headers; 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 → TeachingTip; inline status → InfoBar; system notification → AppNotification.

Step 3: Plan Layout

• Content fills the window — no floating cards on empty backgrounds
• Grid for structure, StackPanel only for simple stacking of few items
• Sidebar: fixed 300-360px width; main content: Width="*" with 24px padding
• Status bar: Grid row at bottom; toolbar: CommandBar or title bar buttons

Step 4: Size the Window to the App

WinUI 3 has no `SizeToContent`. Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. Size the window in `MainWindow`'s constructor; derive from the layout, not a generic.

Rubric. Width = widest row + 48 padding (24 each side), 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 check (ranges, not targets — 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

If your derived number is well below its range, you missed a row — re-check.

AppWindow.Resize takes physical pixels, not DIPs — multiply by the monitor's DPI scale:

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;
        AppWindow.Resize(new SizeInt32((int)(460 * scale), (int)(860 * scale)));
    }
}

XamlRoot.RasterizationScale is null in the ctor and stale after AppWindow.Move, so [DllImport] is the cleanest path. Don't try to size the window by setting Width/Height on the root Grid — that clips content, not the window.

If the user asks for UI validation, see winui-ui-testing Step 3.5 to verify the rubric against the visual checklist.

Step 5: Design Anti-Patterns

XAML Correctness

Theming Rules

• `{ThemeResource BrushName}` at usage sites — updates on theme change
• `{StaticResource}` with ResourceKey redirects inside theme dictionaries — zero allocation
• `ResourceKey` must end in `Brush` (target the SolidColorBrush, not the Color)
• Always define all three variants: x:Key="Light", x:Key="Dark", x:Key="HighContrast" — never use x:Key="Default"
• Verify runtime theme switching: {ThemeResource} updates; {StaticResource} does not

<!-- Correct: StaticResource redirect in theme dictionary -->
<StaticResource x:Key="MyBrush" ResourceKey="ControlFillColorDefaultBrush" />

<!-- Wrong: inline SolidColorBrush allocates new object -->
<SolidColorBrush x:Key="MyBrush" Color="{StaticResource ControlFillColorDefault}" />

High Contrast

Only 8 system color brushes allowed in HC dictionaries:

HC prohibitions: No hardcoded colors, no opacity, no accent colors, no regular WinUI brushes, no SystemColor* in Light/Dark dicts. Use empty HC dict when WinUI defaults suffice. Set HighContrastAdjustment = None at app level.

Typography — Use Styles, Not Raw FontSize

Use SemiBold, never Bold. Minimum 12px. BasedOn styles must not re-declare inherited properties.

Spacing and Layout

• 4px grid: margins, padding, sizes must be multiples of 4 (4, 8, 12, 16, 24, 32, 48)
• ControlCornerRadius (4px) for controls, OverlayCornerRadius (8px) for overlays — never hardcode
• RowSpacing/ColumnSpacing instead of spacer elements
• MinHeight/MinWidth instead of fixed sizing
• No negative margins

Remove Defaults

Don't set WinUI default values — blocks future updates:

• BodyTextBlockStyle on TextBlock, TextFillColorPrimaryBrush foreground, TextWrapping="NoWrap", Padding="0", Margin="0"

Acrylic Pairings

Use BackgroundSizing="InnerBorderEdge" on bordered acrylic. ThemeShadow requires Translation="0,0,32" and 12px parent padding.

Data Binding

• {x:Bind} over {Binding}, explicit Mode=OneWay/TwoWay, x:DataType on DataTemplate
• TextBox `x:Bind TwoWay` — always add `UpdateSourceTrigger=PropertyChanged` so the ViewModel updates on each keystroke instead of waiting for LostFocus. Without it, UIA automation (set-value) and programmatic changes won't commit to the ViewModel.

  <TextBox Text="{x:Bind ViewModel.Name, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}" />

• Commands over Click/Tapped handlers (MVVM)
• VisualStateManager for visual property changes, not code-behind
• No IValueConverter — prefer x:Bind with functions

Bool negation and Visibility functions — define static methods in code-behind:

// In code-behind (e.g., MainPage.xaml.cs)
public static Visibility BoolToVisibility(bool value) =>
    value ? Visibility.Visible : Visibility.Collapsed;
public static Visibility InvertBoolToVisibility(bool value) =>
    value ? Visibility.Collapsed : Visibility.Visible;
public static bool IsNotBusy(bool isLoading) => !isLoading;

<!-- Usage in XAML -->
Visibility="{x:Bind local:MainPage.BoolToVisibility(ViewModel.IsLoading), Mode=OneWay}"
IsEnabled="{x:Bind local:MainPage.IsNotBusy(ViewModel.IsLoading), Mode=OneWay}"

❌ NEVER use Converter={x:Null} — it crashes at runtime.

Accessibility

• AutomationProperties.Name on icon-only controls
• AutomationProperties.AutomationId on all interactive controls
• Semantic controls (Button, HyperlinkButton) — not clickable Border/TextBlock
• DividerStrokeColorDefaultBrush for dividers

Setting attached properties in code-behind — WinUI attached properties use static methods, NOT object initializer syntax:

using Microsoft.UI.Xaml.Automation; // required for AutomationProperties

// ❌ WRONG — object initializer doesn't work for attached properties
var btn = new Button { AutomationProperties = { AutomationId = "BtnSave" } };

// ✅ CORRECT — static setter method
var btn = new Button { Content = "Save" };
AutomationProperties.SetAutomationId(btn, "BtnSave");
AutomationProperties.SetName(btn, "Save button");
Grid.SetRow(btn, 1);
Grid.SetColumn(btn, 0);
ToolTipService.SetToolTip(btn, "Save the current document");

Formatting

• Self-closing tags for childless elements
• Styles referenced with {StaticResource} not {ThemeResource}
• No px suffix on numeric values, no commented-out XAML
• Consistent attribute order: x:Name, AutomationProperties, layout, content, style

References

Approved Brushes

When reviewing XAML, verify that every brush is either: 1. A custom brush with explicit Light, Dark, and HighContrast theme dictionaries, OR 2. One of the approved brushes listed below.

If neither, request the author to switch to an approved brush or provide the complete theme-aware resource set.

Usage

• {ThemeResource BrushName} at usage sites (updates on theme change)
• {StaticResource BrushName} inside theme dictionaries
• Names ending in Brush are SolidColorBrush resources; names without are Color resources
• Prefer the Brush key when assigning to Foreground/Background

Common System Brushes (Quick Reference)

Text Fill

TextFillColorPrimary / TextFillColorPrimaryBrush TextFillColorSecondary / TextFillColorSecondaryBrush TextFillColorTertiary / TextFillColorTertiaryBrush TextFillColorDisabled / TextFillColorDisabledBrush TextFillColorInverse / TextFillColorInverseBrush AccentTextFillColorPrimary / AccentTextFillColorPrimaryBrush AccentTextFillColorSecondary / AccentTextFillColorSecondaryBrush AccentTextFillColorTertiary / AccentTextFillColorTertiaryBrush AccentTextFillColorDisabled / AccentTextFillColorDisabledBrush TextOnAccentFillColorSelectedText / TextOnAccentFillColorSelectedTextBrush TextOnAccentFillColorPrimary / TextOnAccentFillColorPrimaryBrush TextOnAccentFillColorSecondary / TextOnAccentFillColorSecondaryBrush TextOnAccentFillColorDisabled / TextOnAccentFillColorDisabledBrush

Control Fill

ControlFillColorDefault / ControlFillColorDefaultBrush ControlFillColorSecondary / ControlFillColorSecondaryBrush ControlFillColorTertiary / ControlFillColorTertiaryBrush ControlFillColorQuarternary / ControlFillColorQuarternaryBrush ControlFillColorDisabled / ControlFillColorDisabledBrush ControlFillColorTransparent / ControlFillColorTransparentBrush ControlFillColorInputActive / ControlFillColorInputActiveBrush ControlStrongFillColorDefault / ControlStrongFillColorDefaultBrush ControlStrongFillColorDisabled / ControlStrongFillColorDisabledBrush ControlSolidFillColorDefault / ControlSolidFillColorDefaultBrush

Subtle Fill

SubtleFillColorTransparent / SubtleFillColorTransparentBrush SubtleFillColorSecondary / SubtleFillColorSecondaryBrush SubtleFillColorTertiary / SubtleFillColorTertiaryBrush SubtleFillColorDisabled / SubtleFillColorDisabledBrush

Control Alt Fill

ControlAltFillColorTransparent / ControlAltFillColorTransparentBrush ControlAltFillColorSecondary / ControlAltFillColorSecondaryBrush ControlAltFillColorTertiary / ControlAltFillColorTertiaryBrush ControlAltFillColorQuarternary / ControlAltFillColorQuarternaryBrush ControlAltFillColorDisabled / ControlAltFillColorDisabledBrush

Control On Image Fill

ControlOnImageFillColorDefault / ControlOnImageFillColorDefaultBrush ControlOnImageFillColorSecondary / ControlOnImageFillColorSecondaryBrush ControlOnImageFillColorTertiary / ControlOnImageFillColorTertiaryBrush ControlOnImageFillColorDisabled / ControlOnImageFillColorDisabledBrush

Accent Fill

AccentFillColorSelectedTextBackground / AccentFillColorSelectedTextBackgroundBrush AccentFillColorDefault / AccentFillColorDefaultBrush AccentFillColorSecondary / AccentFillColorSecondaryBrush AccentFillColorTertiary / AccentFillColorTertiaryBrush AccentFillColorDisabled / AccentFillColorDisabledBrush

Stroke

ControlStrokeColorDefault / ControlStrokeColorDefaultBrush ControlStrokeColorSecondary / ControlStrokeColorSecondaryBrush ControlStrokeColorOnAccentDefault / ControlStrokeColorOnAccentDefaultBrush ControlStrokeColorOnAccentSecondary / ControlStrokeColorOnAccentSecondaryBrush ControlStrokeColorOnAccentTertiary / ControlStrokeColorOnAccentTertiaryBrush ControlStrokeColorOnAccentDisabled / ControlStrokeColorOnAccentDisabledBrush ControlStrokeColorForStrongFillWhenOnImage / ControlStrokeColorForStrongFillWhenOnImageBrush CardStrokeColorDefault / CardStrokeColorDefaultBrush CardStrokeColorDefaultSolid / CardStrokeColorDefaultSolidBrush ControlStrongStrokeColorDefault / ControlStrongStrokeColorDefaultBrush ControlStrongStrokeColorDisabled / ControlStrongStrokeColorDisabledBrush SurfaceStrokeColorDefault / SurfaceStrokeColorDefaultBrush SurfaceStrokeColorFlyout / SurfaceStrokeColorFlyoutBrush SurfaceStrokeColorInverse / SurfaceStrokeColorInverseBrush DividerStrokeColorDefault / DividerStrokeColorDefaultBrush FocusStrokeColorOuter / FocusStrokeColorOuterBrush FocusStrokeColorInner / FocusStrokeColorInnerBrush

Background Fill

CardBackgroundFillColorDefault / CardBackgroundFillColorDefaultBrush CardBackgroundFillColorSecondary / CardBackgroundFillColorSecondaryBrush CardBackgroundFillColorTertiary / CardBackgroundFillColorTertiaryBrush SmokeFillColorDefault / SmokeFillColorDefaultBrush LayerFillColorDefault / LayerFillColorDefaultBrush LayerFillColorAlt / LayerFillColorAltBrush LayerOnAcrylicFillColorDefault / LayerOnAcrylicFillColorDefaultBrush LayerOnAccentAcrylicFillColorDefault / LayerOnAccentAcrylicFillColorDefaultBrush LayerOnMicaBaseAltFillColorDefault / LayerOnMicaBaseAltFillColorDefaultBrush LayerOnMicaBaseAltFillColorSecondary / LayerOnMicaBaseAltFillColorSecondaryBrush LayerOnMicaBaseAltFillColorTertiary / LayerOnMicaBaseAltFillColorTertiaryBrush LayerOnMicaBaseAltFillColorTransparent / LayerOnMicaBaseAltFillColorTransparentBrush

Solid Background Fill

SolidBackgroundFillColorBase / SolidBackgroundFillColorBaseBrush SolidBackgroundFillColorSecondary / SolidBackgroundFillColorSecondaryBrush SolidBackgroundFillColorTertiary / SolidBackgroundFillColorTertiaryBrush SolidBackgroundFillColorQuarternary / SolidBackgroundFillColorQuarternaryBrush SolidBackgroundFillColorQuinary / SolidBackgroundFillColorQuinaryBrush SolidBackgroundFillColorSenary / SolidBackgroundFillColorSenaryBrush SolidBackgroundFillColorTransparent / SolidBackgroundFillColorTransparentBrush SolidBackgroundFillColorBaseAlt / SolidBackgroundFillColorBaseAltBrush

System Fill

SystemFillColorSuccess / SystemFillColorSuccessBrush SystemFillColorCaution / SystemFillColorCautionBrush SystemFillColorCritical / SystemFillColorCriticalBrush SystemFillColorNeutral / SystemFillColorNeutralBrush SystemFillColorSolidNeutral / SystemFillColorSolidNeutralBrush SystemFillColorAttentionBackground / SystemFillColorAttentionBackgroundBrush SystemFillColorSuccessBackground / SystemFillColorSuccessBackgroundBrush SystemFillColorCautionBackground / SystemFillColorCautionBackgroundBrush SystemFillColorCriticalBackground / SystemFillColorCriticalBackgroundBrush SystemFillColorNeutralBackground / SystemFillColorNeutralBackgroundBrush SystemFillColorSolidAttentionBackground / SystemFillColorSolidAttentionBackgroundBrush SystemFillColorSolidNeutralBackground / SystemFillColorSolidNeutralBackgroundBrush

High Contrast System Brushes

For x:Key="HighContrast" dictionaries only:

SystemColorWindowTextColorBrush SystemColorWindowColorBrush SystemColorButtonFaceColorBrush SystemColorButtonTextColorBrush SystemColorHighlightColorBrush SystemColorHighlightTextColorBrush SystemColorHotlightColorBrush SystemColorGrayTextColorBrush

Code Review Checklist

Theme Support

• [ ] Uses {ThemeResource} for colors/brushes at usage sites
• [ ] Uses {StaticResource} with ResourceKey redirects inside theme dictionaries
• [ ] Custom theme resources define Light, Dark, and HighContrast variants
• [ ] No x:Key="Default" — uses explicit Light/Dark/HighContrast
• [ ] ResourceKey values end in Brush (not the Color name)
• [ ] HC dictionary uses only the 8 system color brushes (no accent, no hardcoded, no WinUI brushes)
• [ ] No opacity on elements or brushes in HC dictionaries
• [ ] No HC resources (SystemColor*) used in Light/Dark dictionaries
• [ ] StaticResource redirects preferred over inline SolidColorBrush in theme dicts
• [ ] Theme dictionary x:Key order consistent across Light/Dark/HighContrast
• [ ] No partial theme updates — Light/Dark changes include matching HighContrast in same PR
• [ ] No ad-hoc themed literals (White/Transparent for themed surfaces)
• [ ] Acrylic surfaces use correct border/background pairings
• [ ] Light and Dark dicts reference the same semantic WinUI keys; differences are intentional
• [ ] Empty HC dict used when WinUI defaults suffice (<ResourceDictionary x:Key="HighContrast" />)
• [ ] HighContrastAdjustment="None" set at app level
• [ ] Accent colors use SystemAccentColor* resources (no hardcoded accent values)
• [ ] Verify runtime theme switching (ThemeResource updates; StaticResource does not)

Data Binding

• [ ] Uses {x:Bind} over {Binding} where possible
• [ ] Mode explicitly set on x:Bind when values change (OneWay/TwoWay)
• [ ] DataTemplate has x:DataType specified
• [ ] No IValueConverter — uses x:Bind with functions
• [ ] Button text uses Content directly, not a nested TextBlock
• [ ] IsEnabled bound from ViewModel readiness state
• [ ] Commands used instead of Click/Tapped event handlers (MVVM)
• [ ] VisualStateManager used for visual property changes (not code-behind)
• [ ] ViewModel state mapped to named properties (bool/enum) instead of complex converter stacks
• [ ] Converters are only simple type conversions; business logic stays in ViewModel
• [ ] No code-behind for styles/colors/layout (exception: HighContrastAdjustment at app level)

Typography

• [ ] Uses system text styles, not hardcoded font properties
• [ ] FontWeight is SemiBold, never Bold
• [ ] BasedOn styles do not re-declare inherited properties
• [ ] Default TextFillColorPrimaryBrush foreground not explicitly set
• [ ] No font sizes below 12px
• [ ] Icon TextBlocks set IsTextScaleFactorEnabled="False"
• [ ] Icon font uses {ThemeResource SymbolThemeFontFamily}, not hardcoded

Layout

• [ ] Uses ControlCornerRadius/OverlayCornerRadius (not hardcoded)
• [ ] Selective corner rounding uses standard radii (e.g., 8,8,0,0)
• [ ] Margins/padding use multiples of 4
• [ ] Uses MinHeight/MinWidth instead of fixed sizing
• [ ] No fixed heights on text containers
• [ ] No fixed button widths (content-driven or MinWidth)
• [ ] Border for single-child containers (not nested Grids)
• [ ] StackPanel does not contain TextBlocks needing TextTrimming
• [ ] RowSpacing/ColumnSpacing used instead of spacer elements
• [ ] No negative margins
• [ ] ThemeShadow has Translation="0,0,32" and 12px parent padding
• [ ] Shadow receiver is behind the elevated element (z-order)
• [ ] BackgroundSizing="InnerBorderEdge" on bordered acrylic elements
• [ ] Mixed-control rows vertically centered

Styles

• [ ] Styles referenced with {StaticResource} (not {ThemeResource})
• [ ] Default WinUI property values not explicitly set (Padding, CornerRadius, etc.)
• [ ] Single-use styles inlined, named style deleted
• [ ] Existing WinUI styles checked before creating custom ones
• [ ] No no-op style churn
• [ ] App-specific resources stay in app or feature dictionaries
• [ ] ThemeResource used inside style setters for themed values
• [ ] VisualStateManager uses AdaptiveTrigger for responsive layout when needed
• [ ] Unused VisualState definitions removed

Resource Organization & Naming

• [ ] Semantic resource keys used (avoid location-based names)
• [ ] Shared resources promoted only when reused across features
• [ ] One-off values remain local (no global resources for single-use)

Accessibility

• [ ] AutomationProperties.Name on icon-only controls
• [ ] Light-dismiss targets are hit-test visible (Background="Transparent")
• [ ] DividerStrokeColorDefaultBrush for dividers (not custom opacity brushes)

Performance

• [ ] x:Load for conditional content
• [ ] x:Phase for list item incremental loading
• [ ] OneTime binding for static content
• [ ] Minimal container nesting

Formatting

• [ ] Uniform indentation (spaces, no tabs)
• [ ] Self-closing tags for childless elements
• [ ] No px suffix on numeric values
• [ ] No commented-out XAML
• [ ] Unused VisualState definitions removed
• [ ] ThemeDictionaries before non-themed resources
• [ ] Namespace declarations ordered consistently (default, x:, platform, WinUI, local)
• [ ] Attribute order consistent across related files
• [ ] No checkpoint files checked in (use _CP locally and remove before commit)

Testing Reminders

If changing brushes: Test in NightSky HC theme, hover on all interactive elements. Include Light/Dark/HC screenshot evidence.

If changing text/containers: Test with text scaling at max and with long/localized strings.

If changing layout: Test at 100%, 150%, 200%, 250% display scaling. Validate Figma at 100% scale.

Colors and Materials Reference

Colors — Theme Resources

Never hardcode colors. Always use {ThemeResource} brushes so your app works in Light, Dark, and High Contrast modes.

Text brushes

Control fill brushes

Background brushes

Accent fill (for primary action buttons)

Stroke / border brushes

Color code examples

<!-- GOOD -->
<Border Background="{ThemeResource CardBackgroundFillColorDefaultBrush}"
        BorderBrush="{ThemeResource CardStrokeColorDefaultBrush}"
        BorderThickness="1"
        CornerRadius="{StaticResource OverlayCornerRadius}"
        Padding="16">
    <TextBlock Text="Card content"
               Foreground="{ThemeResource TextFillColorPrimaryBrush}" />
</Border>

<!-- BAD — hardcoded colors break Dark mode and High Contrast -->
<Border Background="#FFFFFF" BorderBrush="#E0E0E0">
    <TextBlock Text="Card content" Foreground="#000000" />
</Border>

---

Materials — Mica & Acrylic

Mica — use for the app's main window background. It samples the desktop wallpaper for a subtle tinted translucency.

Acrylic — use for transient surfaces (flyouts, menus, sidebars) layered on top of the main window.

<!-- Window-level Mica (set in MainWindow.xaml) -->
<Window.SystemBackdrop>
    <MicaBackdrop />
</Window.SystemBackdrop>

<!-- Alternative: Mica Base Alt (slightly different tint) -->
<Window.SystemBackdrop>
    <MicaBackdrop Kind="BaseAlt" />
</Window.SystemBackdrop>

<!-- Acrylic for in-app surfaces -->
<Window.SystemBackdrop>
    <DesktopAcrylicBackdrop />
</Window.SystemBackdrop>

Materials fall back to solid color on unsupported systems — no code needed.

Control Styles

Built-in WinUI 3 styles and patterns. Use {StaticResource} to reference, BasedOn to extend.

Button Styles

<Button Content="Save" Style="{StaticResource AccentButtonStyle}" />
<Button Content="Cancel" Style="{StaticResource DefaultButtonStyle}" />

Subtle Button Pattern

Override Button.Resources with StaticResource redirects. This preserves the WinUI template and all visual states:

<Button Content="Action">
    <Button.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary x:Key="Light">
                    <StaticResource x:Key="ButtonBackground" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBackgroundPointerOver" ResourceKey="SubtleFillColorSecondaryBrush" />
                    <StaticResource x:Key="ButtonBackgroundPressed" ResourceKey="SubtleFillColorTertiaryBrush" />
                    <StaticResource x:Key="ButtonBorderBrush" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBorderBrushPointerOver" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBorderBrushPressed" ResourceKey="SubtleFillColorTransparentBrush" />
                </ResourceDictionary>
                <ResourceDictionary x:Key="Dark">
                    <StaticResource x:Key="ButtonBackground" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBackgroundPointerOver" ResourceKey="SubtleFillColorSecondaryBrush" />
                    <StaticResource x:Key="ButtonBackgroundPressed" ResourceKey="SubtleFillColorTertiaryBrush" />
                    <StaticResource x:Key="ButtonBorderBrush" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBorderBrushPointerOver" ResourceKey="SubtleFillColorTransparentBrush" />
                    <StaticResource x:Key="ButtonBorderBrushPressed" ResourceKey="SubtleFillColorTransparentBrush" />
                </ResourceDictionary>
                <ResourceDictionary x:Key="HighContrast" />
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </Button.Resources>
</Button>

Empty HC dictionary lets WinUI defaults apply. Light and Dark usually have identical redirects. Border brush states should match background states.

Typography Styles

Rules:

• BodyTextBlockStyle is the default — do not explicitly apply it.
• TextWrapping="NoWrap" is the default — do not set it.
• Use SemiBold, never Bold.
• Minimum 12px for CJK legibility.
• BasedOn styles must not re-declare inherited properties (FontSize, FontFamily, FontWeight, LineHeight).

Style Hygiene

• Reference styles with {StaticResource} (not {ThemeResource} — unnecessary overhead).
• Check for existing WinUI styles before creating custom ones.
• Single-use styles: inline the properties, delete the named style.
• Keep one-off values inline; promote to shared dictionary only when reused.
• Prefer setters/resource overrides for minor visual tweaks; avoid replacing ControlTemplate unless structurally required.
• Use ThemeResource inside style setters for theme-dependent values.
• Avoid no-op style churn.

Naming Conventions

Iconography and Motion Reference

Iconography

Use Segoe Fluent Icons (Windows 11) via the SymbolThemeFontFamily resource, which falls back to Segoe MDL2 Assets on Windows 10 automatically.

Icon types in order of preference

Standard icon sizes: 16px (inline/compact), 20px (default control size), 24px (emphasis), 32px (large), 48px (hero/feature).

Icon code examples

<!-- MenuFlyout with icons -->
<MenuFlyoutItem Text="Copy" Icon="{ui:SymbolIcon Symbol=Copy}">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Key="C" Modifiers="Control" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

<!-- NavigationViewItem with icon -->
<NavigationViewItem Content="Settings" Icon="{ui:SymbolIcon Symbol=Setting}" />

<!-- FontIcon for glyphs not in SymbolIcon enum -->
<FontIcon FontFamily="{StaticResource SymbolThemeFontFamily}"
          Glyph="&#xE8C8;"
          FontSize="16" />

Browse available icons in the WinUI Gallery app → Design guidance → Iconography, or search Segoe Fluent Icons.

---

Corner Radius

Use the built-in theme resources — never hardcode CornerRadius values:

<!-- GOOD — use theme resources -->
<Button CornerRadius="{StaticResource ControlCornerRadius}" Content="Save" />
<Border CornerRadius="{StaticResource OverlayCornerRadius}" Padding="16">
    <!-- Card content -->
</Border>

<!-- BAD — hardcoded values -->
<Button CornerRadius="4" Content="Save" />
<Border CornerRadius="12" />

---

Motion & Transitions

Prefer built-in theme transitions — they animate automatically and respect user "reduce motion" settings.

<!-- Implicit transitions — animate property changes automatically -->
<Button Opacity="1">
    <Button.OpacityTransition>
        <ScalarTransition />
    </Button.OpacityTransition>
</Button>

<!-- Page transitions via Frame -->
<Frame x:Name="ContentFrame">
    <Frame.ContentTransitions>
        <TransitionCollection>
            <NavigationThemeTransition />
        </TransitionCollection>
    </Frame.ContentTransitions>
</Frame>

Connected animations

Animate elements between pages (e.g., list item → detail page):

// Source page — prepare animation
var service = ConnectedAnimationService.GetForCurrentView();
service.PrepareToAnimate("itemAnimation", sourceElement);
Frame.Navigate(typeof(DetailPage), item);

// Destination page — play animation
var animation = ConnectedAnimationService.GetForCurrentView()
    .GetAnimation("itemAnimation");
animation?.TryStart(destinationElement);

Review Guidance Patterns

Concrete guidance patterns for WinUI 3 XAML reviews. Use these as a checklist for common pitfalls and fixes.

1. Brush References Must Target Brush Resources

ResourceKey must reference the SolidColorBrush resource (suffix Brush), not the Color resource.

<!-- Wrong -->
<StaticResource x:Key="TextControlBackground" ResourceKey="ControlFillColorDefault" />

<!-- Correct -->
<StaticResource x:Key="TextControlBackground" ResourceKey="ControlFillColorDefaultBrush" />

Applies to High Contrast as well:

<!-- Wrong -->
<StaticResource x:Key="MyBrush" ResourceKey="SystemColorWindowColor" />

<!-- Correct -->
<StaticResource x:Key="MyBrush" ResourceKey="SystemColorWindowColorBrush" />

2. Prefer StaticResource Redirects Over Inline SolidColorBrush

Inline brushes allocate new objects. Redirect to existing WinUI brushes instead:

<!-- Wrong -->
<SolidColorBrush x:Key="ButtonBackground" Color="{StaticResource ControlFillColorDefault}" />

<!-- Correct -->
<StaticResource x:Key="ButtonBackground" ResourceKey="ControlFillColorDefaultBrush" />

3. High Contrast Rules (Strict)

• Only use the 8 system color brushes in HighContrast dictionaries.
• No hardcoded colors, no opacity, no accent colors, no regular WinUI brushes in HC.
• No gradient animations in HC. Use a single SystemColor brush.
• Use {ThemeResource} only for SystemColor* in HC; use {StaticResource} elsewhere.
• Use empty HC dictionary when WinUI defaults suffice:

<ResourceDictionary x:Key="HighContrast" />

• Set HighContrastAdjustment = ApplicationHighContrastAdjustment.None once at app level.

4. Remove Defaults and Redundant Properties

Avoid setting WinUI default values; it blocks future updates.

<!-- Wrong: defaults -->
<Button Padding="12" Height="32" CornerRadius="4" Content="Action" />

<!-- Correct: only set what differs -->
<Button MinHeight="40" Content="Action" />

Defaults you should not set explicitly:

• BodyTextBlockStyle on TextBlock
• TextFillColorPrimaryBrush on TextBlock
• TextWrapping="NoWrap"
• Padding="0" or Margin="0"
• VerticalAlignment="Top" / HorizontalAlignment="Left"

5. Corner Radius Must Use System Resources

<!-- Correct -->
<Border CornerRadius="{StaticResource ControlCornerRadius}" />
<Border CornerRadius="{StaticResource OverlayCornerRadius}" />

Never hardcode CornerRadius="3" or CornerRadius="7".

6. Typography Must Use Styles

Use system text styles instead of raw font properties:

<!-- Wrong -->
<TextBlock FontSize="14" FontFamily="Segoe UI" FontWeight="Normal" />

<!-- Correct -->
<TextBlock Style="{StaticResource BodyTextBlockStyle}" />

Additional rules:

• Use SemiBold, never Bold.
• Minimum 12px font size.
• BasedOn styles must not re-declare inherited properties.
• Use {ThemeResource SymbolThemeFontFamily} for icon fonts.

7. Text Scaling and Localization

Always validate large text scale and long strings:

• Use MinHeight instead of Height.
• Avoid fixed widths on buttons and text containers.
• Prefer VerticalAlignment="Center" over fixed positioning.
• Test at max text scaling and with long/localized strings.

8. Container Simplification

Remove wrappers that do not add layout or styling:

• If a Button contains only a SymbolIcon, put it directly in Content.
• Use Border for single-child background containers, not Grid.
• Remove StackPanel/Grid wrappers around single elements.

9. TextTrimming Requires Grid Constraints

StackPanel and ColumnDefinition Width="Auto" prevent trimming:

<!-- Wrong -->
<StackPanel Orientation="Horizontal">
    <TextBlock TextTrimming="CharacterEllipsis" />
</StackPanel>

<!-- Correct -->
<Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
</Grid.ColumnDefinitions>
<TextBlock Grid.Column="0" TextTrimming="CharacterEllipsis" />

10. 4px Grid for Layout

All margins, padding, and sizes should be multiples of 4 (4, 8, 12, 16...). Avoid odd values like 3, 5, 7, 11, 15.

11. Flyout and Acrylic Surfaces

Flyout surfaces should use:

Background="{ThemeResource FlyoutPresenterBackground}"
BorderBrush="{ThemeResource FlyoutBorderThemeBrush}"
BorderThickness="{ThemeResource FlyoutBorderThemeThickness}"
CornerRadius="{StaticResource OverlayCornerRadius}"

Acrylic pairings:

• Flyouts/tooltips: AcrylicBackgroundFillColorDefaultBrush + SurfaceStrokeColorFlyoutBrush
• UI surfaces: AcrylicBackgroundFillColorBaseBrush + SurfaceStrokeColorDefaultBrush

Use BackgroundSizing="InnerBorderEdge" on bordered acrylic.

12. ThemeShadow and Elevation

ThemeShadow requires elevation:

Translation="0,0,32"

Add 12px padding on parent to prevent shadow clipping. Prefer ThemeShadow over composition drop shadows.

13. Reused Values Should Be Named Resources

If the same margin/padding/thickness value appears multiple times, extract it into a named resource.

14. Icon Sizing and Spacing

• Prefer FontIcon with FontSize for system icons.
• Use standard even sizes (16, 20, 24, 32).
• Use UniformToFill for non-square images to avoid distortion.
• Keep icon padding consistent on all sides.

15. BasedOn Style Inheritance

When using BasedOn, remove all setters that duplicate the base style. Only keep differences.

17. ScrollViewer Configuration

• VerticalScrollBarVisibility="Auto" (default is Visible).
• HorizontalContentAlignment="Stretch" to prevent content collapse.
• Only the content area should scroll; headers/actions remain fixed.

18. ProgressBar / ProgressRing Defaults

Keep default templates. Custom overrides (CornerRadius, Foreground) have caused contrast and accessibility bugs.

19. Button.Resources for Single-Use Visual States

When customizing a single button's hover/pressed visuals, use Button.Resources with theme dictionaries instead of a new style or template.

Theme-Aware Resources

ThemeResource vs StaticResource

Runtime Theme Switching

Verify runtime theme switching. {ThemeResource} updates when the system theme changes; {StaticResource} does not.

StaticResource Redirects (Preferred Pattern)

Use <StaticResource> with ResourceKey to redirect to an existing WinUI brush. This reuses the existing brush object (zero allocation) instead of creating a new SolidColorBrush inline.

<!-- Correct: redirect -->
<StaticResource x:Key="ButtonBackground" ResourceKey="ControlFillColorDefaultBrush" />

<!-- Wrong: new brush object -->
<SolidColorBrush x:Key="ButtonBackground" Color="{StaticResource ControlFillColorDefault}" />

Theme Dictionary Structure

Always define all three variants. Never use x:Key="Default".

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
        <StaticResource x:Key="MyBrush" ResourceKey="ControlFillColorDefaultBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
        <StaticResource x:Key="MyBrush" ResourceKey="ControlFillColorDefaultBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
        <StaticResource x:Key="MyBrush" ResourceKey="SystemColorWindowTextColorBrush" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

Rules inside theme dictionaries:

• {StaticResource} in Light/Dark (not {ThemeResource} — circular lookup risk)
• {ThemeResource} only for SystemColor* in HighContrast
• ResourceKey must end in Brush
• Keep x:Key order identical across Light/Dark/HighContrast
• Light and Dark should typically reference the same semantic WinUI keys

Accent Colors

Use the system accent color resources:

<!-- User accent color -->
<Border Background="{ThemeResource SystemAccentColor}" />

<!-- Lighter/darker variants -->
<Border Background="{ThemeResource SystemAccentColorLight1}" />
<Border Background="{ThemeResource SystemAccentColorDark1}" />

High Contrast System Colors

The Eight Valid Brushes

For color animations, use the matching Color resource (without "Brush" suffix).

HC Color Pairings

Never mix incompatible pairs.

HC Prohibitions

• No hardcoded colors
• No opacity on elements or brushes
• No accent colors (SystemAccentColor)
• No regular WinUI brushes (TextFillColorPrimaryBrush, etc.)
• No gradient animations — use one solid SystemColor
• No SystemColor* resources in Light/Dark dictionaries

HC Border Thickness

Use 2px border in HC (vs 1px in Light/Dark) for flyouts, dialogs, cards:

<ResourceDictionary x:Key="Light">
    <Thickness x:Key="CardBorderThickness">1</Thickness>
</ResourceDictionary>
<ResourceDictionary x:Key="Dark">
    <Thickness x:Key="CardBorderThickness">1</Thickness>
</ResourceDictionary>
<ResourceDictionary x:Key="HighContrast">
    <Thickness x:Key="CardBorderThickness">2</Thickness>
</ResourceDictionary>

HighContrastAdjustment

Set at app level to prevent system from doubling HC overrides:

Application.Current.HighContrastAdjustment = ApplicationHighContrastAdjustment.None;

ARGB Encoding for Opacity

Encode opacity in alpha channel rather than using Opacity property:

<!-- 25% opacity via alpha channel -->
<SolidColorBrush x:Key="BackplateBrush" Color="#40000000" />

Acrylic Surface Pairings

<Border Background="{ThemeResource AcrylicBackgroundFillColorDefaultBrush}"
        BorderBrush="{ThemeResource SurfaceStrokeColorFlyoutBrush}"
        BorderThickness="1"
        CornerRadius="{StaticResource OverlayCornerRadius}"
        BackgroundSizing="InnerBorderEdge"
        Translation="0,0,32">
    <Border.Shadow>
        <ThemeShadow />
    </Border.Shadow>
</Border>

Overlays on acrylic use LayerOnAcrylicFillColorDefaultBrush. Dividers use DividerStrokeColorDefaultBrush.

Dialog Overlays (Smoke)

For dim overlays behind dialogs or modals, use:

<Border Background="{ThemeResource ContentDialogSmokeFill}" />

Windows 10 to 11 Migration

Typography and Spacing Reference

Typography — Type Ramp

Use the built-in TextBlock styles — never set FontSize or FontWeight manually. The type ramp uses Segoe UI Variable and scales correctly across displays.

Always reference these StaticResource styles — never hardcode font sizes, weights, or line heights.

<!-- GOOD — use built-in styles -->
<TextBlock Text="Settings" Style="{StaticResource SubtitleTextBlockStyle}" />
<TextBlock Text="Choose your preferences below." Style="{StaticResource BodyTextBlockStyle}" />
<TextBlock Text="Last updated: 3/10/2026" Style="{StaticResource CaptionTextBlockStyle}" />

<!-- BAD — never hardcode font properties -->
<TextBlock Text="Settings" FontSize="20" FontWeight="SemiBold" />

Minimum readable sizes: 12px Regular for labels, 14px SemiBold for smallest bold text. Never go below 12px.

---

Spacing — 4px Grid

All spacing and sizing values must be multiples of 4px. This ensures consistent alignment and scaling across DPI settings.

Standard spacing scale (effective pixels):

<!-- GOOD — multiples of 4 -->
<StackPanel Spacing="8">
    <TextBlock Text="Name" Style="{StaticResource BodyStrongTextBlockStyle}" />
    <TextBox PlaceholderText="Enter your name" />
</StackPanel>

<Grid Padding="36" RowSpacing="24" ColumnSpacing="16">
    <!-- Page content with standard padding and section spacing -->
</Grid>

<!-- BAD — arbitrary values -->
<StackPanel Spacing="10" Margin="15,7,15,7" />