Avalonia

Workflow

1. Inspect the SDK, target frameworks, Avalonia package versions, .axaml files, entrypoint, and supported OS/RIDs. Keep Avalonia packages on one compatible version. Use the Avalonia 12 docs for 12 and the Avalonia 11 docs for 11; do not copy 12-only APIs into 11.
2. Keep Program.BuildAvaloniaApp, App.axaml, views, view models, and domain/services separate. Desktop hosts use StartWithClassicDesktopLifetime and create MainWindow in OnFrameworkInitializationCompleted; single-view targets require their own lifetime. The previewer can have no application lifetime.
3. Use typed compiled bindings and explicit binding modes. x:DataType describes the binding type; it does not set the runtime DataContext. Avalonia 12 enables compiled bindings by default; explicitly enable them on 11. Read references/bindings-and-controls.md for templates, properties, resources, and command patterns.
4. Use CommunityToolkit.Mvvm for observable state and commands when appropriate. Prefer cancellable asynchronous service operations, surface errors, and marshal background updates to the UI dispatcher. Keep services independent of controls.
5. Choose StyledProperty for styleable/animatable values and DirectProperty for backed state without style precedence. Use DataTemplate to display data and ControlTemplate/ControlTheme to change a control's visual structure. Use UserControl for application composition, TemplatedControl for reusable skinnable controls, and custom rendering only when needed.
6. Validate native integrations, dialogs, resources, shutdown, DPI, accessibility, and packaging on each supported platform. Read references/platforms-and-publishing.md before trimming or Native AOT. Read the documentation map only for the selected topic.