Ultimate Avalonia Framework

A comprehensive Claude Code skill for building cross-platform desktop applications with Avalonia UI and .NET. Covers project setup, MVVM architecture, control customization, platform integration, packaging, and deployment across Windows, macOS, and Linux.

When to Use This Skill

Choose Ultimate Avalonia Framework when:

• You're building a new cross-platform desktop application with .NET
• You need to set up an Avalonia project with proper architecture
• You want to implement custom controls, themes, or styling
• You need platform-specific integration (file system, notifications, tray icons)
• You're packaging and distributing an Avalonia app

Consider alternatives when:

• You want Zafiro-specific layouts (use an Avalonia Layout Zafiro skill)
• You need web-based UI (use a web frontend skill)
• You want mobile-only apps (use a mobile development skill)

Quick Start

Copy
# Create a new Avalonia project
dotnet new avalonia.app -o MyApp --framework net8.0

# Install the skill
claude install ultimate-avalonia-framework

# Set up the project
claude "Set up an Avalonia MVVM project with ReactiveUI, dependency injection, and a multi-window layout"

# Add custom controls
claude "Create a custom DataGrid control with sorting, filtering, and row selection for my Avalonia app"

Core Concepts

Avalonia vs Other Desktop Frameworks

Feature	Avalonia	WPF	MAUI	Electron
Platforms	Win, Mac, Linux, Web	Windows only	Win, Mac, iOS, Android	Win, Mac, Linux
Language	C#, XAML	C#, XAML	C#, XAML	JS/TS, HTML
Performance	Native rendering	Native (Win)	Native per platform	Chromium-based
Bundle Size	~30MB	~5MB (framework included)	~50MB	~100MB+
Ecosystem	Growing	Mature	Growing	Massive

MVVM Architecture

Views (XAML) → Visual layout, no logic
    ↕ Data Binding
ViewModels (C#) → Presentation logic, commands
    ↕ Services
Models (C#) → Business logic, data access

Project Structure:
├── Views/
│   ├── MainWindow.axaml
│   ├── DashboardView.axaml
│   └── SettingsView.axaml
├── ViewModels/
│   ├── MainWindowViewModel.cs
│   ├── DashboardViewModel.cs
│   └── SettingsViewModel.cs
├── Models/
│   └── AppSettings.cs
├── Services/
│   └── DataService.cs
└── App.axaml (theme + DI setup)

Control Hierarchy

Control Type	Examples	Customization
Layout	StackPanel, Grid, DockPanel, WrapPanel	Properties only
Input	TextBox, ComboBox, Slider, DatePicker	Styles + templates
Display	TextBlock, Image, Border, ProgressBar	Styles
Collection	ListBox, DataGrid, TreeView, ItemsRepeater	DataTemplates
Navigation	TabControl, Carousel, SplitView	Templates
Feedback	ProgressBar, Notification, Dialog	Custom implementations

Configuration

Parameter	Type	Default	Description
target_framework	string	"net8.0"	.NET version: net8.0, net9.0
mvvm_framework	string	"reactive_ui"	MVVM: reactive_ui, community_toolkit
di_container	string	"microsoft"	DI: microsoft, autofac, dry_ioc
platforms	string[]	["win", "mac", "linux"]	Target platforms
theme	string	"fluent"	Theme: fluent, simple, custom

Best Practices

1. Use ReactiveUI for MVVM — ReactiveUI's reactive extensions integrate naturally with Avalonia's binding system. WhenAnyValue, reactive commands, and observable interactions make complex UI logic clean and testable.

2. Design for all three platforms from the start — Test on Windows, macOS, and Linux regularly. Platform differences in font rendering, file paths, and system integration surface early in development.

3. Use DataTemplates for dynamic content — Instead of creating views imperatively, define DataTemplates that automatically render the appropriate view for each view model type. This keeps your navigation clean and type-safe.

4. Optimize startup time — Desktop apps should launch in under 2 seconds. Use ahead-of-time (AOT) compilation, lazy-load non-essential services, and defer heavy initialization until after the main window is visible.

5. Package properly for each platform — Windows users expect .msi or .msix installers. macOS users expect .dmg or .app bundles. Linux users expect .deb, .rpm, or AppImage. Use platform-appropriate packaging tools.

Common Issues

Different rendering on different platforms — Avalonia renders with Skia, so it should be consistent, but font availability and system DPI settings vary. Include your fonts as embedded resources and handle DPI scaling properly.

XAML designer doesn't show preview — Install the Avalonia extension for your IDE. JetBrains Rider has the best Avalonia designer support. Visual Studio support requires the Avalonia VS extension.

App crashes on macOS with M1/M2 — Ensure you're building for ARM64 architecture. Use dotnet publish -r osx-arm64 for Apple Silicon. Universal binaries that include both x64 and ARM64 are recommended for distribution.