XAML Best Practices

Analogy categoryAnalogies

Organizing Resources and Styles for Reuse

Large XAML codebases stay maintainable when colors, brushes, font sizes, and control styles live in dedicated ResourceDictionary files merged through MergedDictionaries rather than being duplicated inline on individual controls, because a single source of truth for a brush like PrimaryBrush means a rebrand touches one file instead of hundreds. Structuring resources into layered dictionaries — a Colors.xaml for raw palette values, a Typography.xaml for font resources, and a Styles.xaml that references both — mirrors how design tokens are organized in modern design systems and keeps each file focused on a single concern, which also reduces merge conflicts when multiple developers touch styling simultaneously.

🏏

Cricket analogy: Centralizing brushes in one ResourceDictionary is like a franchise standardizing its team jersey supplier contract in one master agreement instead of each player negotiating kit deals individually, so a sponsor logo change updates everywhere at once.

Choosing the Right Container and Avoiding Layout Overwork

Panel choice directly affects both readability and rendering performance: a Grid with explicit RowDefinitions/ColumnDefinitions is the right tool for structured, form-like layouts, while a StackPanel suits simple linear flows, and nesting several Grids inside StackPanels inside more Grids 'just to get it working' produces layout passes that measure and arrange far more elements than necessary, which becomes visible as jank when scrolling long lists. A common performance mistake is using a Grid with Auto-sized rows/columns purely for alignment when a simpler StackPanel with Margin would achieve the same visual result with a cheaper layout pass, and conversely, using nested StackPanels to fake a table layout when a single Grid with defined rows and columns would both look more correct and measure faster.

🏏

Cricket analogy: Choosing Grid for structured layouts versus StackPanel for simple flows is like choosing a set fielding formation for a spin bowler versus a simple straight field for a pace bowler — using the wrong formation for the situation wastes energy repositioning fielders unnecessarily.

Bindings, Converters, and MVVM Discipline

Keep code-behind thin by binding directly to view-model properties and commands rather than reaching into the visual tree from event handlers, and prefer compiled bindings (x:Bind in UWP/MAUI, CompiledBinding in Avalonia) over classic reflection-based Binding wherever the platform supports it, both for performance and for catching typos at build time. Value converters implementing IValueConverter should stay small and single-purpose — a BoolToVisibilityConverter should only ever convert a bool to a visibility value, not also apply business logic — because converters embedded with side effects are notoriously hard to unit test and tend to be silently invoked far more often than developers expect, including during design-time rendering.

🏏

Cricket analogy: Keeping code-behind thin and delegating to the view-model is like a captain trusting the bowling coach's pre-set field plan rather than personally repositioning fielders after every single ball, letting each role focus on its own responsibility.

xml

<!-- Good: shared resources, structured Grid, compiled binding, single-purpose converter -->
<ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="/Resources/Colors.xaml" />
    <ResourceDictionary Source="/Resources/Typography.xaml" />
</ResourceDictionary.MergedDictionaries>

<Grid RowDefinitions="Auto,*" ColumnDefinitions="120,*"
      Background="{StaticResource SurfaceBrush}">
    <TextBlock Grid.Row="0" Grid.ColumnSpan="2"
               Text="Account Settings"
               Style="{StaticResource HeadingStyle}" />
    <TextBlock Grid.Row="1" Grid.Column="0" Text="Notifications" />
    <ToggleSwitch Grid.Row="1" Grid.Column="1"
                  IsOn="{x:Bind ViewModel.NotificationsEnabled, Mode=TwoWay}" />
</Grid>

Use x:Static or CompiledBinding/x:Bind wherever your platform supports it — the compile-time error you get from a typo'd property name is far cheaper to fix than a silent runtime binding failure discovered only by a QA tester clicking through the app.

Avoid deeply nested panel hierarchies purely for alignment convenience — each extra Grid or StackPanel layer adds a measure-and-arrange pass, and in long virtualized lists this compounds into visible scroll jank. Profile with your platform's layout visualizer before assuming a nested layout is 'fine'.

Centralize colors, typography, and styles in merged ResourceDictionary files instead of duplicating values inline.
Layer resource files by concern (Colors, Typography, Styles) to reduce merge conflicts and ease rebranding.
Choose Grid for structured layouts and StackPanel for simple linear flows; avoid unnecessary nesting.
Nested panels used only for alignment convenience add extra layout passes and can cause scroll jank.
Prefer compiled bindings (x:Bind, CompiledBinding) over classic reflection-based Binding where supported.
Keep code-behind thin by binding to view-model commands and properties instead of manipulating the visual tree directly.
Keep value converters small and single-purpose so they remain easy to unit test and reason about.