All recipes assume the design tokens from avalonia-pro-max/design-system are loaded (SurfaceBrush, AccentBrush, TextPrimaryBrush, RadiusLg, Space*, etc.).
Buttons
Reusable Button Styles
<!-- Styles/Buttons.axaml -->
<Styles xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
Usage:
<Button Classes="primary" Content="Save"/>
<Button Classes="secondary" Content="Cancel"/>
<Button Classes="ghost icon" ToolTip.Tip="Settings"
AutomationProperties.Name="Settings">
<PathIcon Data="{StaticResource SettingsIconGeometry}"/>
</Button>
<Button Classes="danger" Content="Delete account"/>
<Button Classes="primary lg" Content="Get started"/>
Card
<Border Classes="card">
<StackPanel Spacing="{StaticResource Space2}">
<TextBlock Classes="h3" Text="Total revenue"/>
<TextBlock FontSize="{StaticResource FontSize2xl}"
FontWeight="SemiBold"
Text="$48,294"/>
<TextBlock Classes="muted" Text="+12.4% vs last month"/>
</StackPanel>
</Border>
<Style Selector="Border.card">
<Setter Property="Background" Value="{DynamicResource SurfaceElevatedBrush}"/>
<Setter Property="BorderBrush" Value="{DynamicResource BorderBrush}"/>
<Setter Property="BorderThickness" Value="1"/>
<Setter Property="CornerRadius" Value="{StaticResource RadiusLg}"/>
<Setter Property="Padding" Value="{StaticResource PaddingCard}"/>
<Setter Property="BoxShadow" Value="{StaticResource ShadowSm}"/>
</Style>
<Style Selector="Border.card.interactive">
<Setter Property="Cursor" Value="Hand"/>
<Setter Property="Transitions">
<Transitions>
<BoxShadowsTransition Property="BoxShadow" Duration="0:0:0.15"/>
</Transitions>
</Setter>
</Style>
<Style Selector="Border.card.interactive:pointerover">
<Setter Property="BoxShadow" Value="{StaticResource ShadowMd}"/>
</Style>
Labeled section (GroupBox, 12.0+)
For a titled group of related controls (settings groups, filter panels) use the built-in GroupBox instead of a hand-built Border + header TextBlock. It is a HeaderedContentControl (Header, Content) that you can style via Border.card-style tokens:
<GroupBox Header="Notifications">
<StackPanel Spacing="{StaticResource Space2}">
<CheckBox Content="Email"/>
<CheckBox Content="Push"/>
</StackPanel>
</GroupBox>
In 11.3 GroupBox does not exist — keep the Border.card + header TextBlock pattern above (or a FluentAvalonia/third-party equivalent).
Read-only Table (TableView, 12.1+)
For read-only tabular data in 12.1+, prefer the built-in TableView (Avalonia.Controls, derives from ListBox, virtualized, Columns, CanUserResizeColumns, bound via ItemsSource) over DataGrid. DataGrid (Avalonia.Controls.DataGrid) is in maintenance mode in 12.x. Use DataGrid (or TreeDataGrid) when you need editing, sorting UI or hierarchy, and in 11.3/12.0 where TableView does not exist. Check the TableView docs (https://docs.avaloniaui.net) for current column element names before writing column XAML. Style it with the same tokens as lists: row height >= 36 px, Border header with TextMutedBrush, 1 px row separators, no zebra striping unless the data is wide.
Sidebar Navigation (FluentAvalonia NavigationView)
<ui:NavigationView xmlns:ui="using:FluentAvalonia.UI.Controls"
PaneDisplayMode="Left"
IsPaneToggleButtonVisible="True"
OpenPaneLength="240"
IsBackButtonVisible="False"
AlwaysShowHeader="False">
<ui:NavigationView.MenuItems>
<ui:NavigationViewItem Content="Dashboard" Tag="dashboard">
<ui:NavigationViewItem.IconSource>
<ui:SymbolIconSource Symbol="Home"/>
</ui:NavigationViewItem.IconSource>
</ui:NavigationViewItem>
<ui:NavigationViewItem Content="Projects" Tag="projects">
<ui:NavigationViewItem.IconSource>
<ui:SymbolIconSource Symbol="Folder"/>
</ui:NavigationViewItem.IconSource>
</ui:NavigationViewItem>
<ui:NavigationViewItemSeparator/>
<ui:NavigationViewItem Content="Team" Tag="team">
<ui:NavigationViewItem.IconSource>
<ui:SymbolIconSource Symbol="People"/>
</ui:NavigationViewItem.IconSource>
</ui:NavigationViewItem>
</ui:NavigationView.MenuItems>
<ui:NavigationView.FooterMenuItems>
<ui:NavigationViewItem Content="Settings" Tag="settings">
<ui:NavigationViewItem.IconSource>
<ui:SymbolIconSource Symbol="Setting"/>
</ui:NavigationViewItem.IconSource>
</ui:NavigationViewItem>
</ui:NavigationView.FooterMenuItems>
<ui:Frame x:Name="ContentFrame"/>
</ui:NavigationView>
For non-FluentAvalonia apps, build a sidebar with SplitView:
<SplitView IsPaneOpen="True"
DisplayMode="CompactInline"
OpenPaneLength="240"
CompactPaneLength="56">
<SplitView.Pane>
<Border Background="{DynamicResource SurfaceMutedBrush}">
<ListBox ItemsSource="{Binding NavItems}"
SelectedItem="{Binding SelectedNav}"
Background="Transparent">
<ListBox.ItemTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal" Spacing="12">
<PathIcon Data="{Binding IconGeometry}" Width="16" Height="16"/>
<TextBlock Text="{Binding Label}" VerticalAlignment="Center"/>
</StackPanel>
</DataTemplate>
</ListBox.ItemTemplate>
</ListBox>
</Border>
</SplitView.Pane>
<ContentControl Content="{Binding CurrentView}"/>
</SplitView>
App Shell (Title bar + sidebar + content)
Version notes: ExtendClientAreaToDecorationsHint / ExtendClientAreaTitleBarHeightHint below work in 11.x and 12.x (on Windows 12.0+ the old margin-when-maximized workarounds must be removed). ExtendClientAreaChromeHints is removed in 12 and SystemDecorations is replaced by WindowDecorations — see layout-patterns (Window Chrome).
<Window xmlns="https://github.com/avaloniaui"
ExtendClientAreaToDecorationsHint="True"
ExtendClientAreaTitleBarHeightHint="40"
TransparencyLevelHint="AcrylicBlur"
Background="Transparent">
<Panel>
<ExperimentalAcrylicBorder IsHitTestVisible="False">
<ExperimentalAcrylicBorder.Material>
<ExperimentalAcrylicMaterial
BackgroundSource="Digger"
TintColor="{DynamicResource SurfaceBackgroundColor}"
TintOpacity="1"
MaterialOpacity="0.65"/>
</ExperimentalAcrylicBorder.Material>
</ExperimentalAcrylicBorder>
<DockPanel>
<!-- Custom title bar -->
<Border DockPanel.Dock="Top" Height="40"
IsHitTestVisible="False">
<TextBlock Text="My App" Margin="16,0"
VerticalAlignment="Center"
Foreground="{DynamicResource TextSecondaryBrush}"/>
</Border>
<!-- Main content -->
<ContentControl Content="{Binding CurrentView}"/>
</DockPanel>
</Panel>
</Window>
Dialog (FluentAvalonia ContentDialog)
var dialog = new ContentDialog
{
Title = "Delete project?",
Content = "This action cannot be undone. All files will be permanently deleted.",
PrimaryButtonText = "Delete",
CloseButtonText = "Cancel",
DefaultButton = ContentDialogButton.Close
};
dialog.PrimaryButtonClick += (_, _) => viewModel.ConfirmDelete();
await dialog.ShowAsync();
For destructive actions, style the primary button with the danger class via PrimaryButtonStyle.
Form with Inline Validation
<StackPanel Spacing="{StaticResource Space4}" MaxWidth="400">
<StackPanel Spacing="{StaticResource Space1}">
<TextBlock Text="Email" Classes="label"/>
<TextBox Text="{Binding Email, Mode=TwoWay,
UpdateSourceTrigger=LostFocus}"
PlaceholderText="you@example.com"/> <!-- (12.0+); use Watermark="..." (11.x) in 11.3 projects -->
<TextBlock Text="{Binding EmailError}"
IsVisible="{Binding HasEmailError}"
Classes="error"/>
</StackPanel>
<StackPanel Spacing="{StaticResource Space1}">
<TextBlock Text="Password" Classes="label"/>
<TextBox PasswordChar="•"
Text="{Binding Password, Mode=TwoWay}"/>
<TextBlock Text="At least 12 characters" Classes="helper"/>
</StackPanel>
<Button Classes="primary lg"
Content="Create account"
Command="{Binding CreateAccountCommand}"
IsEnabled="{Binding !IsBusy}"
HorizontalAlignment="Stretch"/>
</StackPanel>
<Style Selector="TextBlock.label">
<Setter Property="FontSize" Value="13"/>
<Setter Property="FontWeight" Value="Medium"/>
<Setter Property="Foreground" Value="{DynamicResource TextSecondaryBrush}"/>
</Style>
<Style Selector="TextBlock.helper">
<Setter Property="FontSize" Value="12"/>
<Setter Property="Foreground" Value="{DynamicResource TextMutedBrush}"/>
</Style>
<Style Selector="TextBlock.error">
<Setter Property="FontSize" Value="12"/>
<Setter Property="Foreground" Value="{DynamicResource DangerBrush}"/>
</Style>
<Style Selector="TextBox:error /template/ Border#PART_BorderElement">
<Setter Property="BorderBrush" Value="{DynamicResource DangerBrush}"/>
</Style>
Use INotifyDataErrorInfo on the ViewModel; the :error pseudoclass auto-applies.
Empty State
<Border Classes="card">
<StackPanel Spacing="{StaticResource Space4}"
HorizontalAlignment="Center"
Margin="0,48">
<PathIcon Data="{StaticResource InboxIconGeometry}"
Width="48" Height="48"
Foreground="{DynamicResource TextMutedBrush}"/>
<TextBlock Classes="h3" Text="No projects yet"
HorizontalAlignment="Center"/>
<TextBlock Classes="muted"
Text="Create your first project to get started"
HorizontalAlignment="Center"
TextAlignment="Center"
MaxWidth="280"/>
<Button Classes="primary"
Content="New project"
HorizontalAlignment="Center"
Command="{Binding CreateProjectCommand}"/>
</StackPanel>
</Border>
Toast / Notification (Avalonia built-in)
// In Window/UserControl
private WindowNotificationManager _notif;
protected override void OnLoaded(RoutedEventArgs e)
{
base.OnLoaded(e);
_notif = new WindowNotificationManager(TopLevel.GetTopLevel(this))
{
Position = NotificationPosition.BottomRight,
MaxItems = 3
};
}
_notif.Show(new Notification(
"Project created",
"‘Acme website redesign’ is ready.",
NotificationType.Success));
Badge
<Border CornerRadius="{StaticResource RadiusFull}"
Background="{DynamicResource AccentBrush}"
Padding="8,2"
VerticalAlignment="Center">
<TextBlock Text="{Binding Count}"
FontSize="11"
FontWeight="SemiBold"
Foreground="White"/>
</Border>
Status variants: swap Background to SuccessBrush, WarningBrush, DangerBrush, or muted (SurfaceMutedBrush + TextSecondaryBrush).
Skeleton (loading placeholder)
<Border Background="{DynamicResource SurfaceMutedBrush}"
CornerRadius="{StaticResource RadiusSm}"
Height="14" Width="180">
<Border.Styles>
<Style Selector="Border">
<Style.Animations>
<Animation Duration="0:0:1.4" IterationCount="Infinite">
<KeyFrame Cue="0%"><Setter Property="Opacity" Value="0.4"/></KeyFrame>
<KeyFrame Cue="50%"><Setter Property="Opacity" Value="0.8"/></KeyFrame>
<KeyFrame Cue="100%"><Setter Property="Opacity" Value="0.4"/></KeyFrame>
</Animation>
</Style.Animations>
</Style>
</Border.Styles>
</Border>
Use Ursa.Avalonia's Skeleton control if you depend on Ursa.
Settings Row (FluentAvalonia SettingsExpander pattern)
<StackPanel Spacing="{StaticResource Space3}">
<ui:SettingsExpander Header="Appearance"
Description="Choose how the app looks">
<ui:SettingsExpander.IconSource>
<ui:SymbolIconSource Symbol="Color"/>
</ui:SettingsExpander.IconSource>
<ui:SettingsExpanderItem Content="Theme">
<ui:SettingsExpanderItem.Footer>
<ComboBox SelectedItem="{Binding SelectedTheme}"
ItemsSource="{Binding ThemeOptions}"
MinWidth="160"/>
</ui:SettingsExpanderItem.Footer>
</ui:SettingsExpanderItem>
<ui:SettingsExpanderItem Content="Accent color">
<ui:SettingsExpanderItem.Footer>
<ColorPicker Color="{Binding AccentColor}"/>
</ui:SettingsExpanderItem.Footer>
</ui:SettingsExpanderItem>
</ui:SettingsExpander>
</StackPanel>
Common Mistakes
- Hand-rolling button styles per view — define once in
Styles/Buttons.axaml, useClasses="..."everywhere. Padding="10"on an icon-only button — total target shrinks below 36px, fails 44pt accessibility on touch.- Forgetting
AutomationProperties.Nameon icon-only buttons — screen readers announce nothing. - Validating with red-only feedback — combine
:errorborder with helper text. - Using
Watermarkin a 12.x project — obsolete; usePlaceholderText(12.0+) andPlaceholderForeground(12.0+, TextBox/AutoCompleteBox/CalendarDatePicker/NumericUpDown) to tint it from tokens. - Cards stacked at the same elevation — use
ShadowSmor 1px border, notShadowLg, for in-page cards. - Using
ContentDialogfor non-blocking info — use a toast/notification instead.