Avalonia Layout Zafiro Studio

A Claude Code skill for building modern, clean, and maintainable Avalonia UI layouts using the Zafiro.Avalonia framework. Focuses on semantic containers, shared styles, and minimal XAML for creating professional cross-platform desktop applications with .NET.

When to Use This Skill

Choose Avalonia Layout Zafiro when:

• You're building a cross-platform desktop app with Avalonia UI
• You want clean, maintainable XAML layouts using Zafiro conventions
• You need to implement Material Design-inspired layouts in Avalonia
• You want to use Zafiro's layout containers and styling helpers
• You're setting up navigation, panels, and responsive layouts

Consider alternatives when:

• You need general Avalonia framework setup (use an Avalonia framework skill)
• You want WPF-specific layouts (use a WPF skill)
• You need web-based UI (use a web frontend skill)

Quick Start

Copy
# Install the skill
claude install avalonia-layout-zafiro-studio

# Create a layout
claude "Create a main window layout with sidebar navigation, toolbar, and content area using Zafiro containers"

# Set up navigation
claude "Implement page navigation in Avalonia with a Zafiro sidebar: Dashboard, Settings, Users, Reports"

# Build responsive panels
claude "Create a responsive split panel layout that collapses the sidebar on narrow windows"

Core Concepts

Zafiro Layout Containers

Container	Purpose	Usage
ZafiroWindow	Main window with built-in chrome	App shell
NavigationView	Sidebar + content navigation	Main navigation
CommandBar	Toolbar with actions	Top toolbar
ContentArea	Main content region	Page content
Card	Elevated content container	Data cards
Dialog	Modal overlay	Confirmations, forms

XAML Layout Principles

Copy
<!-- Semantic containers over nested grids -->
<ZafiroWindow>
  <NavigationView>
    <NavigationView.MenuItems>
      <NavigationViewItem Content="Dashboard" Icon="Home" />
      <NavigationViewItem Content="Settings" Icon="Settings" />
    </NavigationView.MenuItems>

    <ContentArea>
      <!-- Page content here -->
    </ContentArea>
  </NavigationView>
</ZafiroWindow>

Style Organization

Layer	File	Contents
Theme	Themes/Base.axaml	Colors, fonts, base styles
Controls	Styles/Controls.axaml	Control-level overrides
Layout	Styles/Layout.axaml	Spacing, sizing utilities
Page	Views/*.axaml	Page-specific styles (inline)

Configuration

Parameter	Type	Default	Description
theme	string	"light"	Theme: light, dark, system
navigation	string	"sidebar"	Navigation: sidebar, tabs, breadcrumb
responsive	boolean	true	Enable responsive layout breakpoints
material	boolean	true	Use Material Design-inspired styling
mvvm_framework	string	"reactive_ui"	MVVM: reactive_ui, community_toolkit, prism

Best Practices

1. Use semantic containers over Grid nesting — Zafiro provides purpose-built containers like NavigationView and ContentArea. Three levels of nested Grids with star sizing is a sign you should use a semantic container instead.

2. Keep XAML minimal — Every line of XAML is visual debt. Use shared styles for repeated patterns, data templates for data-driven UI, and control templates only when you need fundamental behavior changes.

3. Separate styles from layout — Put reusable styles in resource dictionaries, not inline on every control. A button's color, padding, and font should come from a shared style, not repeated attributes.

4. Use MVVM consistently — Keep views dumb and view models smart. Views should have zero logic — only bindings and converters. This makes your layouts testable and maintainable.

5. Design for keyboard navigation — Desktop apps need full keyboard accessibility. Ensure tab order is logical, all actions have keyboard shortcuts, and focus indicators are visible.

Common Issues

Layout doesn't resize properly — Use proportional sizing (*, Auto) instead of fixed pixel sizes. Avoid hardcoding widths and heights. Use MinWidth/MaxWidth for constraints without rigidity.

Styles not applying — Check the resource dictionary merge order in App.axaml. Styles must be merged before the views that use them. Also verify that style selectors match the control type exactly.

Navigation doesn't update content — Ensure your navigation framework (ReactiveUI routing, Prism regions) is properly configured. The NavigationView selection change must trigger navigation to the corresponding view model.