home / skills / sickn33 / antigravity-awesome-skills / avalonia-layout-zafiro

avalonia-layout-zafiro skill

safe

This skill helps you craft modern Avalonia layouts with Zafiro.Avalonia, promoting semantic containers, shared styles, and minimal XAML.

This is most likely a fork of the avalonia-layout-zafiro skill from xfstudio

npx playbooks add skill sickn33/antigravity-awesome-skills --skill avalonia-layout-zafiro

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.3 KB

---
name: avalonia-layout-zafiro
description: Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# Avalonia Layout with Zafiro.Avalonia

> Master modern, clean, and maintainable Avalonia UI layouts.
> **Focus on semantic containers, shared styles, and minimal XAML.**

## 🎯 Selective Reading Rule

**Read ONLY files relevant to the layout challenge!**

---

## 📑 Content Map

| File | Description | When to Read |
|------|-------------|--------------|
| `themes.md` | Theme organization and shared styles | Setting up or refining app themes |
| `containers.md` | Semantic containers (`HeaderedContainer`, `EdgePanel`, `Card`) | Structuring views and layouts |
| `icons.md` | Icon usage with `IconExtension` and `IconOptions` | Adding and customizing icons |
| `behaviors.md` | `Xaml.Interaction.Behaviors` and avoiding Converters | Implementing complex interactions |
| `components.md` | Generic components and avoiding nesting | Creating reusable UI elements |

---

## 🔗 Related Project (Exemplary Implementation)

For a real-world example, refer to the **Angor** project:
`/mnt/fast/Repos/angor/src/Angor/Avalonia/Angor.Avalonia.sln`

---

## ✅ Checklist for Clean Layouts

- [ ] **Used semantic containers?** (e.g., `HeaderedContainer` instead of `Border` with manual header)
- [ ] **Avoided redundant properties?** Use shared styles in `axaml` files.
- [ ] **Minimized nesting?** Flatten layouts using `EdgePanel` or generic components.
- [ ] **Icons via extension?** Use `{Icon fa-name}` and `IconOptions` for styling.
- [ ] **Behaviors over code-behind?** Use `Interaction.Behaviors` for UI-logic.
- [ ] **Avoided Converters?** Prefer ViewModel properties or Behaviors unless necessary.

---

## ❌ Anti-Patterns

**DON'T:**
- Use hardcoded colors or sizes (literals) in views.
- Create deep nesting of `Grid` and `StackPanel`.
- Repeat visual properties across multiple elements (use Styles).
- Use `IValueConverter` for simple logic that belongs in the ViewModel.

**DO:**
- Use `DynamicResource` for colors and brushes.
- Extract repeated layouts into generic components.
- Leverage `Zafiro.Avalonia` specific panels like `EdgePanel` for common UI patterns.

Overview

This skill provides practical guidelines for building modern, maintainable Avalonia UI layouts using Zafiro.Avalonia. It emphasizes semantic containers, shared styles, generic components, and minimizing XAML redundancy to keep views readable and consistent. The guidance targets teams and individual developers who want predictable, reusable UI patterns across an application.

How this skill works

The approach inspects view structure and replaces ad-hoc primitives with semantic containers like HeaderedContainer, EdgePanel, and Card. It centralizes visual properties into axaml themes and styles, pushes UI logic into Behaviors and ViewModels instead of converters or code-behind, and promotes icon usage via IconExtension and IconOptions. The result is flatter layouts, fewer repeated properties, and components that scale across screens and features.

When to use it

When consolidating duplicated XAML properties across multiple views.
When views suffer from deep Grid/StackPanel nesting and hard-to-maintain layouts.
When building a design system or shared component library for an Avalonia app.
When migrating code-behind or converters into behaviors and viewmodel logic.
When standardizing icon usage and theming across an application.

Best practices

Prefer semantic containers (HeaderedContainer, EdgePanel, Card) over raw Borders and manual headers.
Define colors, brushes, and repeated visual properties in shared axaml theme files and use DynamicResource.
Flatten layout hierarchies using EdgePanel and generic components to reduce nesting complexity.
Use Interaction.Behaviors for UI interactions and keep ViewModels responsible for state and simple logic.
Use IconExtension and IconOptions for consistent icon styling; avoid hardcoded icon attributes in views.
Avoid IValueConverter for logic that belongs in the ViewModel; use converters only for true presentation transforms.

Example use cases

Refactor a complex settings page by extracting repeated sections into Card components and applying shared styles.
Create a consistent app header using HeaderedContainer and a theme resource for spacing and typography.
Replace multiple icon declarations with the IconExtension and IconOptions to enforce a single visual language.
Simplify nested layout stacks by switching to EdgePanel for common edge-aligned layouts (toolbar, status bar).
Migrate simple converter logic into ViewModel properties and use Behaviors for interaction-driven UI updates.

FAQ

Can I keep some converters?

Yes—use converters only for presentation-only transformations that don’t belong in a ViewModel, but prefer ViewModel properties or Behaviors for decision logic.

How do I start migrating an existing app?

Begin by extracting repeated styles into axaml theme files, then replace the most common repeated layouts with semantic containers and components incrementally.

Are EdgePanel and HeaderedContainer part of Avalonia core?

They come from Zafiro.Avalonia; adopt them where they simplify patterns and keep fallbacks for standard controls if needed.