Icon System Overview
FluentAvalonia provides a flexible icon system with multiple display methods and reusable resources. The system consists of two main parts:
- Icon Elements – UI controls that display icons directly
- Icon Sources – Reusable resources that define icon appearances
FluentAvalonia Icon System Architecture
Sources: samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml26-176 samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml179-284
Icon Elements
FluentAvalonia provides specialized icon elements that inherit from the base FAIconElement class:
| Icon Element | Purpose | Key Properties |
|---|---|---|
ui:SymbolIcon |
Fluent Icons collection | Symbol, FontSize |
ui:FontIcon |
Font glyphs | Glyph, FontFamily, FontSize |
ui:FAPathIcon |
Vector paths | Data, Width, Height |
ui:BitmapIcon |
Bitmap images | UriSource, ShowAsMonochrome |
ui:ImageIcon |
Various image sources | Source, Width, Height |
SymbolIcon
The ui:SymbolIcon control displays icons from Microsoft’s Fluent Icons collection embedded in the FluentAvalonia assembly.
|
1 |
<ui:SymbolIcon Symbol="Save" FontSize="18" /> |
The Symbol property accepts values from the Symbol enum, which contains predefined icons matching WinUI.
FontIcon
The ui:FontIcon control displays font glyphs as icons, commonly used with SymbolThemeFontFamily.
|
1 |
<ui:FontIcon Glyph="A" FontSize="18" FontFamily="Cascadia Code" /> |
FAPathIcon
The ui:FAPathIcon control displays vector paths as icons.
|
1 2 3 |
<ui:FAPathIcon Data="M12,18.17L8.83,15L7.42,16.41L12,21L16.59,16.41L15.17,15M12,5.83L15.17,9L16.58,7.59L12,3L7.41,7.59L8.83,9L12,5.83Z" Width="50" Height="50" /> |
BitmapIcon
The ui:BitmapIcon control displays bitmap images with optional monochrome conversion.
|
1 2 3 4 |
<ui:BitmapIcon UriSource="avares://FAControlsGallery/Assets/avalonia-logo.ico" ShowAsMonochrome="True" Width="50" Height="50" /> |
ImageIcon
The ui:ImageIcon control displays various image types including DrawingImage.
|
1 2 3 4 5 |
<ui:ImageIcon Width="100" Height="100"> <DrawingImage> <!-- Complex drawing content --> </DrawingImage> </ui:ImageIcon> |
Sources: samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml28-176
Icon Sources
Icon sources provide reusable icon definitions that can be referenced throughout your application. They mirror the available icon elements:
| Icon Source | Purpose | Key Properties |
|---|---|---|
ui:SymbolIconSource |
Fluent Icons collection | Symbol, FontSize |
ui:FontIconSource |
Font glyphs | Glyph, FontFamily, FontSize |
ui:PathIconSource |
Vector paths | Data |
ui:BitmapIconSource |
Bitmap images | UriSource, ShowAsMonochrome |
ui:ImageIconSource |
Various image sources | Source |
Icon sources are typically defined in resource dictionaries:
|
1 2 3 4 5 6 7 |
<UserControl.Resources> <ui:SymbolIconSource x:Key="SaveIcon" Symbol="Save" FontSize="18" /> <ui:PathIconSource x:Key="SamplePathIcon" Data="M12,18.17L8.83,15L7.42,16.41L12,21L16.59,16.41L15.17,15M12,5.83L15.17,9L16.58,7.59L12,3L7.41,7.59L8.83,9L12,5.83Z" /> <ui:FontIconSource x:Key="FGlyph" Glyph="F" FontSize="18" /> <ui:BitmapIconSource x:Key="AvaloniaLogo" UriSource="avares://FAControlsGallery/Assets/avalonia-logo.ico" /> <ui:ImageIconSource x:Key="AvaloniaLogoImage" Source="avares://FAControlsGallery/Assets/avalonia-logo.ico" /> </UserControl.Resources> |
Icon Source Usage Patterns
Icon sources can be used in two ways:
- Direct IconSource Property: Controls like
ui:InfoBaracceptIconSourcedirectly - IconSourceElement: Use
ui:IconSourceElementto display icon sources anywhere
Sources: samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml13-17 samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml182-281
Symbol Enumeration
FluentAvalonia provides predefined icons through the Symbol enum, corresponding to the WinUI Fluent Icon collection with both filled and regular variants.
Symbol System Architecture
Symbol Usage
The symbols can be used in multiple ways:
- SymbolIcon with Symbol enum:
|
1 |
<ui:SymbolIcon Symbol="Save" FontSize="18" /> |
- SymbolIconSource in resources:
|
1 |
<ui:SymbolIconSource Symbol="Save" FontSize="18" /> |
- FontIcon with SymbolThemeFontFamily:
|
1 |
<ui:FontIcon Glyph="&#xE7BA;" FontFamily="{StaticResource SymbolThemeFontFamily}" FontSize="20" /> |
Symbol Browser Implementation
The FAControlsGallery includes a searchable symbol browser that displays all available symbols with their names, glyphs, and Unicode points:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<ui:ItemsRepeater ItemsSource="{Binding Path=View, Source={StaticResource IconsSource}}"> <ui:ItemsRepeater.ItemTemplate> <DataTemplate x:DataType="vm:SymbolItem"> <Border> <Panel> <TextBlock Text="{CompiledBinding Symbol}" /> <ui:FontIcon Glyph="{Binding Glyph}" FontFamily="{StaticResource SymbolThemeFontFamily}" FontSize="28"/> <TextBlock Text="{CompiledBinding UnicodePoint}" /> </Panel> </Border> </DataTemplate> </ui:ItemsRepeater.ItemTemplate> </ui:ItemsRepeater> |
Sources: samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml286-347 samples/FAControlsGallery/Pages/DesignPages/DesignIconsPage.axaml39-43 samples/FAControlsGallery/Styling/ControlExampleStyles.axaml48-49
Color System
FluentAvalonia provides a comprehensive color system following the WinUI color palette, organized into categories and available as XAML resources.
Color System Architecture
Color Categories
FluentAvalonia organizes colors into functional categories:
| Category | Purpose | Common Brushes |
|---|---|---|
| Text Colors | Text elements with emphasis levels | TextFillColorPrimaryBrush, TextFillColorSecondaryBrush, TextFillColorTertiaryBrush |
| Fill Colors | Interactive control fills | ControlFillColorDefaultBrush, ControlFillColorSecondaryBrush, ControlFillColorTertiaryBrush |
| Stroke Colors | Borders and outlines | ControlStrokeColorDefaultBrush, ControlStrokeColorSecondaryBrush, CardStrokeColorDefaultBrush |
| Background Colors | Various background types | CardBackgroundFillColorDefaultBrush, SolidBackgroundFillColorBaseBrush, LayerFillColorDefaultBrush |
| Signal Colors | Status indicators | SystemFillColorCriticalBrush, SystemFillColorSuccessBrush |
Sources: samples/FAControlsGallery/Pages/DesignPages/ColorsPage.axaml87-123 samples/FAControlsGallery/Pages/DesignPages/BackgroundColorsPage.axaml1-308
Color Categories
FluentAvalonia organizes colors into several main categories, each with specific use cases:
Text Colors
Used for text elements with different emphasis levels (primary, secondary, tertiary).
Fill Colors
Used for filling UI controls and elements like buttons, toggles, and other interactive components.
Stroke Colors
Used for borders and outlines of UI elements.
Background Colors
Used for different types of backgrounds in the application:
- Solid Background: Base backgrounds for the application
- Card Background: For card-like UI elements
- Layer: For layered UI components
- Mica Background: Matches Windows 11 Mica material (simulated in Avalonia)
- Acrylic Background: Matches Windows acrylic material (simulated in Avalonia)
- Accent Acrylic Background: Accent-colored acrylic backgrounds
Signal Colors
Used for status indicators, warnings, and other informational elements.
Sources: samples/FAControlsGallery/Pages/DesignPages/BackgroundColorsPage.axaml10-305
Using Colors in XAML
Colors in FluentAvalonia are accessed through DynamicResource markup extensions. Each color is available both as a raw color value and as a brush.
|
1 2 3 4 5 |
<!-- Using a color directly --> <Border BorderBrush="{DynamicResource CardStrokeColorDefault}" /> <!-- Using the corresponding brush --> <Border BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}" /> |
Color Naming Convention
| Resource Type | Naming Pattern | Example |
|---|---|---|
| Color | [Category][Purpose][Variant] |
CardStrokeColorDefault |
| Brush | [Category][Purpose][Variant]Brush |
CardStrokeColorDefaultBrush |
Color Variants
| Variant | Purpose | Usage |
|---|---|---|
Default |
Standard variant | Rest state |
Secondary |
Less prominent | Hover state |
Tertiary |
Least prominent | Pressed state |
Disabled |
Disabled state | Disabled controls |
Selected |
Selected state | Selected items |
State-Based Color Usage
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<Style Selector="TabStripItem"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource ControlFillColorDefaultBrush}"</span><span class="xml"> /></span> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"BorderBrush"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource ControlElevationBorderBrush}"</span><span class="xml"> /></span> </Style> <Style Selector="TabStripItem:pointerover"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource ControlFillColorSecondaryBrush}"</span><span class="xml"> /></span> </Style> <Style Selector="TabStripItem:pressed"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource ControlFillColorTertiaryBrush}"</span><span class="xml"> /></span> </Style> <Style Selector="TabStripItem:selected"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource AccentFillColorDefaultBrush}"</span><span class="xml"> /></span> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"BorderBrush"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource ControlStrokeColorOnAccentDefaultBrush}"</span><span class="xml"> /></span> </Style> |
Sources: samples/FAControlsGallery/Pages/DesignPages/ColorsPage.axaml89-104 samples/FAControlsGallery/Pages/DesignPages/ColorsPage.axaml11-75
Background Color Categories
FluentAvalonia provides specialized background colors for different UI elements and layering scenarios.
Card Background Colors
Used to create “cards” – content blocks that live on pages and layer backgrounds:
|
1 2 3 4 5 6 7 |
<Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}" BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}" BorderThickness="1" CornerRadius="{StaticResource ControlCornerRadius}" BackgroundSizing="InnerBorderEdge"> <!-- Card content here --> </Border> |
| Card Background Brush | Description | Usage |
|---|---|---|
CardBackgroundFillColorDefaultBrush |
Standard card background | Default card color |
CardBackgroundFillColorSecondaryBrush |
Slightly darker alternative | Alternate card color |
CardBackgroundTertiaryBrush |
Hover and pressed states | Interactive card states |
Solid Background Colors
Used for the base layers of an application:
| Solid Background Brush | Description | Usage |
|---|---|---|
SolidBackgroundFillColorBaseBrush |
Base background | Bottom-most layer |
SolidBackgroundFillColorBaseAltBrush |
Alternative base background | Alternative bottom layer |
SolidBackgroundFillColorSecondaryBrush |
Secondary background | Darker background option |
SolidBackgroundFillColorTertiaryBrush |
Tertiary background | Content layer color |
SolidBackgroundFillColorQuarternaryBrush |
Quaternary background | Alt content layer color |
Layer Colors
Used for layering content on top of backgrounds:
| Layer Brush | Description | Usage |
|---|---|---|
LayerFillColorDefaultBrush |
Standard layer | Content layer color |
LayerFillColorAltBrush |
Alternative layer | Alternate content layer |
LayerOnAcrylicFillColorDefaultBrush |
Layer on acrylic surfaces | Acrylic content layer |
LayerOnMicaBaseAltFillColorDefaultBrush |
Layer on Mica base | Active tab rest, content layer |
LayerOnMicaBaseAltFillColorTertiaryBrush |
Layer on Mica base tertiary | Active tab drag |
LayerOnMicaBaseAltFillColorTransparentBrush |
Layer on Mica base transparent | Inactive tab rest |
LayerOnMicaBaseAltFillColorSecondaryBrush |
Layer on Mica base secondary | Inactive tab hover |
Specialized Background Colors
Mica Background Colors
|
1 2 3 |
<Border Background="{DynamicResource MicaBackgroundFillColorBaseBrush}"> <!-- Mica-style content --> </Border> |
MicaBackgroundFillColorBaseBrush: Bottom-most layer of Mica experienceMicaBackgroundFillColorBaseAltBrush: Default tab band background
Acrylic Background Colors
|
1 2 3 |
<Border Background="{DynamicResource AcrylicBackgroundFillColorBaseBrush}"> <!-- Acrylic-style content --> </Border> |
AcrylicBackgroundFillColorBaseBrush: Bottom-most layer of acrylic surface (uses fallback color)AcrylicBackgroundFillColorDefaultBrush: Default acrylic recipe for flyouts (uses fallback color)
Accent Acrylic Background Colors
|
1 2 3 |
<Border Background="{DynamicResource AccentAcrylicBackgroundFillColorBaseBrush}"> <!-- Accent acrylic content --> </Border> |
AccentAcrylicBackgroundFillColorBaseBrush: Bottom-most layer of accent acrylic surfaceAccentAcrylicBackgroundFillColorDefaultBrush: Default accent acrylic recipe
Sources: samples/FAControlsGallery/Pages/DesignPages/BackgroundColorsPage.axaml10-305
Best Practices
Icons
- Consistency: Use the same icon style throughout your application
- Standard Sizes: Keep icons at standard sizes (16px, 18px, 20px, 24px, 28px, 32px)
- Color Inheritance: Icons inherit foreground color by default, adapting to themes
- Icon Sources: Use icon sources in resource dictionaries for reusable icons
- Accessibility: Ensure icons have proper
AutomationProperties.Namefor screen readers - Symbol Font: Use
SymbolThemeFontFamilyfor consistent icon appearance
|
1 2 3 4 5 6 7 8 9 10 |
<!-- Good: Standard icon with proper size --> <ui:SymbolIcon Symbol="Save" FontSize="18" /> <!-- Better: Reusable icon source --> <ui:IconSourceElement IconSource="{StaticResource SaveIcon}" /> <!-- Good: Accessibility support --> <Button AutomationProperties.Name="Copy sample code" ToolTip.Tip="Copy sample code"> <ui:SymbolIcon Symbol="ClipboardCode" FontSize="20" /> </Button> |
Colors
- Dynamic Resources: Always use
DynamicResourceinstead ofStaticResourcefor colors to support theme changes - Purpose-Based Usage: Use colors according to their intended purpose (text colors for text, fill colors for controls)
- Hierarchy Respect: Use primary, secondary, and tertiary variants appropriately for visual hierarchy
- BackgroundSizing: Use
BackgroundSizing="InnerBorderEdge"on borders with backgrounds for proper rendering - High Contrast Support: The color system automatically adapts to high contrast themes
- Proper Naming: Follow the established naming convention for color resources
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<!-- Good: Proper text color hierarchy --> <TextBlock Text="Primary Text" Foreground="{DynamicResource TextFillColorPrimaryBrush}" /> <TextBlock Text="Secondary Text" Foreground="{DynamicResource TextFillColorSecondaryBrush}" /> <!-- Good: Proper border and background usage --> <Border Background="{DynamicResource CardBackgroundFillColorDefaultBrush}" BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}" BorderThickness="1" CornerRadius="{StaticResource ControlCornerRadius}" BackgroundSizing="InnerBorderEdge"> <!-- Content --> </Border> <!-- Good: State-based color usage --> <Style Selector="ListBoxItem"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource CardBackgroundFillColorDefaultBrush}"</span><span class="xml"> /></span> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"BorderBrush"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource CardStrokeColorDefaultBrush}"</span><span class="xml"> /></span> </Style> <Style Selector="ListBoxItem:selected"> <span class="xml"><</span><span class="xml">Setter</span> <span class="xml">Property</span><span class="xml">=</span><span class="xml">"Background"</span> <span class="xml">Value</span><span class="xml">=</span><span class="xml">"{DynamicResource AccentFillColorDefaultBrush}"</span><span class="xml"> /></span> </Style> |
Sources: samples/FAControlsGallery/Styling/ControlExampleStyles.axaml47-49 samples/FAControlsGallery/Pages/DesignPages/BackgroundColorsPage.axaml13-21 samples/FAControlsGallery/Pages/DesignPages/DesignIconsPage.axaml19-60
Exploring Available Resources
The FAControlsGallery sample application provides comprehensive pages to explore:
- Available icons under the “Icons” page in the Controls section
- Available colors under the “Colors” page in the Design section
These pages allow you to see all available options and get the appropriate resource names for use in your application.
Sources: samples/FAControlsGallery/Pages/FAControlsPages/IconsPage.axaml1-350 samples/FAControlsGallery/Pages/DesignPages/ColorsPage.axaml1-126 samples/FAControlsGallery/Pages/DesignPages/BackgroundColorsPage.axaml1-308
