Md3.Avalonia.Dock 0.5.0-preview.2

Md3.Avalonia

English | 简体中文

A Material Design 3 control library and component gallery for Avalonia 12.

https://github.com/user-attachments/assets/53c05bc6-f1b5-4076-8b62-c4a7a2b819bf

• 353 public API types for buttons, inputs, navigation, dialogs, charts, and motion; indexed in the API reference and checked by a script gate.

• HCT dynamic color: any seed color, 6 schemes, 3 contrast levels, and 49 color roles.

• Bundles the official Material Symbols Rounded font; checksum and glyph count are verified at build time.

• 18 independently installable NuGet packages; third-party integration themes are opt-in.

• Each control has its own CLR type and scoped ControlTheme, without replacing native Avalonia controls.

• The core package does not depend on Avalonia.Themes.Fluent or Avalonia.Themes.Simple.

• Desktop and Android targets; every package declares IsTrimmable and IsAotCompatible.

Current preview: 0.5.0-preview.2. The install examples below use this version. Preview APIs may still receive compatibility changes. See Known limitations for manual screen-reader and Android-device validation status.

Contents

• Requirements
• Install
• Quick start
• NuGet packages
• Theming
• Controls overview
• Repository layout
• Build and test
• Documentation
• Known limitations
• License

Requirements

Install

Install the core package

dotnet add package Md3.Avalonia --version 0.5.0-preview.2

Add optional packages as needed; all packages use the same version

dotnet add package Md3.Avalonia.Icons --version 0.5.0-preview.2

Quick start

Register the theme

<Application xmlns="https://github.com/avaloniaui"
             xmlns:themes="using:Md3.Avalonia.Themes"
             xmlns:extra="using:Md3.Avalonia.Extra.Themes">
  <Application.Styles>
    <themes:MaterialTheme />
    
    <extra:ExtraTheme />
  </Application.Styles>
</Application>

Use the controls

<Window xmlns="https://github.com/avaloniaui"
        xmlns:md="using:Md3.Avalonia.Controls">
  <StackPanel Spacing="16" Margin="24">
    <md:MdButton Content="Continue" Variant="Filled" Command="{Binding ContinueCommand}" />
    <md:MdTextBox Label="Project name" Text="{Binding ProjectName}" MaxLength="40" />
    <md:MdComboBox Label="Platform" Variant="Outlined"
                   ItemsSource="{Binding Platforms}" SelectedItem="{Binding Platform}" />
  </StackPanel>
</Window>

All bindable APIs are Avalonia properties and work directly with CommunityToolkit.MVVM; controls can also be constructed and used from code.

Material 3 actions	Material 3 components

NuGet packages

All 18 packages share one version and can be installed independently; unused packages are not pulled in.

Each third-party theme package is the only package that brings in its upstream dependency, keeping those dependencies out of the core package. The Markdown, LiveCharts2, ScottPlot, Mapsui, and InkCanvas packages do not register in Application.Styles: Markdown styles are assigned to the document control, while the others expose object-level entry points.

Design principles

• Each interactive control has its own Md* CLR type and scoped ControlTheme, while reusing Avalonia's native behavior, binding, keyboard, and selection models where possible.

• Consume color, typography, shape, state layers, elevation, and motion through tokens and DynamicResource.

• If a font or icon provider is missing or fails validation, keep the icon hidden instead of substituting a similar-looking glyph.

Theming

Light, Dark, and System modes all consume theme tokens through DynamicResource. Apply any seed color at startup or at runtime:

var options = new MdThemeOptions
{
    SeedColor = "#006A6A",
    SchemeVariant = MdThemeSchemeVariant.Expressive,
    ContrastLevel = MdThemeContrastLevel.High,
    ThemeMode = MdThemeMode.System
};
var dark = Application.Current!.ActualThemeVariant == ThemeVariant.Dark;
MdThemeManager.Apply(Application.Current, options, dark);
var json = MdThemeJson.Serialize(options);

The MaterialColorUtilities HCT generator supports six schemes (TonalSpot, Neutral, Vibrant, Expressive, Monochrome, Fidelity), three contrast levels (Standard, Medium, High), and 49 color roles. It also provides System and Component token layers, contrast diagnostics, and theme JSON round-tripping.

Embedded official Material Symbols font

Md3.Avalonia.Icons ships the complete Google Material Symbols Rounded variable TTF. Md3.Avalonia.Icons.Lite ships a genuine outline subset generated from the same file; consumers do not need to download or register a font manually.

The source is pinned to commit 737e3324305806514d7909874fa1818ae1808232 of google/material-design-icons. The complete TTF has SHA-256 95b24392bb49efd1bc3e92cff4e2452ad094461bab7c97e7d8723fab97e330ca. Both local builds and CI run:

python3 scripts/verify-fonts.py

The verifier checks checksums, variable-font tables, and glyph counts for the full font and Lite subset. It rejects missing, placeholder, or substituted binaries. After referencing Core and Icons, there is no need to call ConfigureFonts manually: the provider is discovered and registered automatically, and symbol glyphs remain hidden if validation fails.

Controls overview

The online DocFX API reference is generated from the C# XML comments in all 18 packages. docs/API.md describes package coverage and documentation sources. scripts/check-api-doc-coverage.py scans all 353 public types; the table lists representative types in each group.

All Button, Icon Button, and FAB templates use MdRipplePresenter: ripples originate at the press point, clip to the full container shape, and support Expressive, Standard, Reduced, and None motion schemes. The Elevated MdButton variant is retained for compatibility but is deprecated in M3; prefer another variant for new interfaces.

Md3.Avalonia.Extra is an optional clean-room extension package and does not claim to reproduce the full API of corresponding Flutter packages. For precise parity details, see docs/FLUTTER_PARITY_STATUS.md; similar Md* type names alone do not imply full compatibility.

Repository layout

src/Md3.Avalonia/                  #  Core controls and design tokens; no specific icon-font dependency
├─ Controls/                       #  Md* controls, enums, and property APIs
├─ Motion/                         #  Motion schemes, spring tokens, and transitions
└─ Themes/
   ├─ MaterialTheme.axaml
   ├─ Tokens/                      #  11 token dictionaries
   └─ Controls/                    #  Scoped ControlTheme for each control
src/Md3.Avalonia.Icons/            #  Icon provider with the complete official TTF embedded
src/Md3.Avalonia.Extra/            #  Flutter-inspired extension controls
src/Md3.Avalonia.<Vendor>/         #  12 opt-in third-party theme packages, each the sole upstream dependency entry point
src/Md3.Avalonia.Notifications/    #  Native system notifications, independent of Avalonia UI

gallery/Md3.Avalonia.Gallery/          #  Desktop Gallery: 108 component pages + Theme Lab
gallery/Md3.Avalonia.Gallery.Android/  #  net10.0-android single-view host
tests/Md3.Avalonia.HeadlessTests/      #  API, input, theme, regression, and rendering tests
tests/.../Spec/                        # Layered spec checks (L1 tokens / L2 geometry / L3 golden images / L5 motion)
docs/                                  #  API, compatibility, publishing, and validation docs
spec-snapshot/                         #  External-source expected-value oracle and ratchet policy

See docs/SPEC_VERIFICATION.md for the responsibilities of each spec-verification layer, the ratchet process, and known gaps.

Build and test

python3 scripts/verify-fonts.py     #  Verify embedded fonts
bash scripts/build-nuget.sh         # Build all 18 .nupkg / .snupkg packages

dotnet build gallery/Md3.Avalonia.Gallery.Desktop/Md3.Avalonia.Gallery.Desktop.csproj -c Release
dotnet test tests/Md3.Avalonia.HeadlessTests/Md3.Avalonia.HeadlessTests.csproj -c Release

Install the Android workload before building the full solution:

dotnet workload install android
dotnet build Md3.Avalonia.sln -c Release

The following static checks do not require the .NET SDK:

python3 scripts/lint-design-tokens.py       #  Lint design tokens
python3 scripts/check-api-doc-coverage.py   #  Check DocFX projects, XML output, and bilingual interface docs
python3 scripts/check-gallery-localization.py --strict

Publish the desktop Gallery with native AOT (Linux requires clang/zlib; --smoke also requires xvfb):

bash scripts/publish-gallery-aot.sh --rid linux-x64 --smoke   # Other supported RIDs: win-x64 / osx-x64 / osx-arm64

The script verifies that the output is a native executable with no managed DLL beside it. --smoke runs the binary under xvfb to check that trimming has not removed runtime reflection metadata. .github/workflows/aot-probe.yml runs the same script on the main and arena branches.

The release gate builds all 18 packages and verifies 18 .nupkg files, 18 .snupkg files, a unified version, and the embedded official font. Releases use NuGet Trusted Publishing; see docs/PUBLISHING.md for setup.

Clean build artifacts immediately after every build, test, or pack operation. Do not ship bin/, obj/, TestResults/, DLLs, PDBs, NuGet packages, APKs, or AABs in the repository; docs/*.png are retained as documentation reference images.

Documentation

Known limitations

• Manual validation is not signed off. Narrator, VoiceOver, Orca, and TalkBack must be tested by people with the corresponding OS and assistive technology, following the release checklist. A successful Android APK build is not device validation; ARM64, rotation, lifecycle, and TalkBack still require on-device sign-off. Results are tracked in docs/RELEASE_VALIDATION.md.
• Motion. Ripple, spring tokens, and inherited motion schemes are in place. The four M3 transitions—shared-axis, fade-through, container transform, and animated visibility—are implemented (MdRevealHost yields layout space and clips; MdMorphPanel interpolates endpoint sizes), but Control content does not cross-fade on exit.
• AOT. All 18 packages declare IsTrimmable and IsAotCompatible and enable the corresponding analyzers; theme JSON uses source-generated serialization. The Linux x64 native Gallery has been published and smoke-run under xvfb. The AOT workflow reports diagnostics, but zero diagnostics do not mean AOT validation has passed for Windows, macOS, Android, or a consuming application.
• Android back gestures and safe areas. MdBackNavigation covers dialogs, sheets, drawers, search, menus, FAB menus, and both pickers. MdSafeArea provides per-edge insets. Headless behavior has regression tests; on-device gesture animation and cutout geometry still need manual validation.
• RTL and localization. Related adaptation code remains in place, but full RTL/multilingual layout and manual screen-reader validation are not currently preview release blockers.
• Font provenance. The complete Material Symbols Rounded variable TTF and genuine Lite subset are checked in and packaged automatically. CI pins the upstream commit and verifies SHA-256, variable tables, and glyph counts to prevent placeholder or substituted fonts from entering a release.

See spec-snapshot/manifest.json for the official pages, pinned AndroidX commit e2171b56112f43bf962f5d608413f74033b580b6, and token version.

License

Apache-2.0. See LICENSE and THIRD-PARTY-NOTICES.md for the license terms of third-party components. The embedded Material Symbols font is also Apache-2.0; its license is distributed with both Icons packages.