avalonia-app-builder

name: avalonia-app-builder description: Build, refactor, debug, and review AvaloniaUI desktop applications in C#. Use when requests mention Avalonia, .axaml views, XAML UI, ViewModel or ViewLocator wiring, compiled bindings and x:DataType, CommunityToolkit.Mvvm [ObservableProperty] partial properties, ResourceDictionary.ThemeDictionaries, StyledProperty or DirectProperty usage, or Avalonia styling/theming conventions.

Avalonia App Builder

Workflow

1. Confirm project conventions before coding.
2. Implement UI in Avalonia XAML (not control construction in code-behind).
3. Implement view-model state with CommunityToolkit.Mvvm partial observable properties.
4. Wire views/view-models using ViewLocator naming conventions.
5. Apply binding and theming rules.
6. Validate class/member ordering and compiled-binding coverage.

Core Conventions

UI and XAML

• Use Avalonia-specific XAML for layout and visuals.
• Avoid creating controls in code-behind unless explicitly required by the user.
• Define styles/resources in dedicated dictionaries and merge them in App.axaml.
• Use StaticResource for immutable values and DynamicResource only when runtime updates are needed.
• For light/dark resources, use:

<ResourceDictionary.ThemeDictionaries>
  <!-- theme dictionaries -->
</ResourceDictionary.ThemeDictionaries>

MVVM and Properties

• Use CommunityToolkit.Mvvm version >= 8.4.0 patterns.
• Define observable properties as partial properties:

[ObservableProperty]
public partial string Title { get; set; } = string.Empty;

• Prefer one-way bindings unless user input must update the view-model.

Binding Rules

• Use compiled bindings only. Set explicit x:DataType on all binding scopes:
  • Views
  • DataTemplates
  • Control themes
  • Resource dictionaries where bindings are used
• Do not write logical expressions in bindings (for example, && or combined conditions).
• Boolean inversion with ! is allowed for a single bound boolean:
  • Valid: {Binding !IsConnecting}
  • Invalid: {Binding !IsConnecting && !IsUpdating}

ViewLocator Conventions

• Respect ViewLocator naming:
  • MyViewModel resolves to MyView.axaml
• Keep view-model and view names aligned to avoid runtime lookup failures.

Custom Controls

• Use StyledProperty only when the value must participate in styling.
• Prefer DirectProperty for non-styled properties.
• Prefer custom controls or control re-templating for strong UX, instead of CRUD-like default layouts.

C# Member Ordering

Order members by access level and member type. Use this structure:

1. public members
2. internal members
3. protected members
4. private members

Within each access level, order by:

1. fields
2. constructors
3. properties
4. commands
5. events
6. methods

Delivery Checklist

Before finishing, verify:

• All new/changed UI is written in Avalonia XAML.
• All bindings are compiled and have correct x:DataType scopes.
• No invalid logical binding expressions were introduced.
• View/view-model names follow ViewLocator convention.
• Theme resources use ResourceDictionary.ThemeDictionaries where needed.
• View-model observable properties use toolkit partial-property style.
• Member ordering follows the required class layout.

Reference

• Avalonia repository: https://github.com/AvaloniaUI/Avalonia