AtomUI: bringing the Ant Design language to Avalonia desktop apps

The problem: a desktop framework with no design system attached

Avalonia gives you a way to write one user interface for Windows, macOS and Linux, and it gives you a rendering system and a styling system. What it does not give you is a set of controls that look finished, a theme you can hand to a designer to change, and a set of enterprise patterns like tables, cascaders and colour pickers that behave the way people expect on a work machine.

AtomUI is that layer. The project describes itself as an Ant Design 6 component system for Avalonia and .NET desktop applications, bringing Ant Design's enterprise interaction patterns, visual language, design tokens and theme customization model to native cross-platform apps. The Ant Design badge in the project description points at version 6 of the design system, which tells you that this is a port of a specific, current generation rather than an interpretation of an older look.

The audience is desktop application teams, specifically those building software that looks like the web applications their users already know, without running a browser. That is a real population: admin panels, internal tools, monitoring consoles, configuration editors, all of which are the kind of software where Ant Design is close to a default choice, and where a WPF or Avalonia developer would otherwise rebuild a DataGrid from scratch.

The licence is LGPL-3.0, the default branch is release/6.0, and the project is not archived with the last push on 2026-10-19. The published releases are v6.2.6 on 2026-10-19, v6.1.3 on 2026-08-09 and v6.1.0 on 2026-07-20, so the 6.x line is where the work is.

The package set, and why it is split the way it is

The NuGet layout is the clearest statement of the project's priorities, so it is worth reading rather than skimming.

The main package is AtomUI.Desktop.Controls, described as the desktop control library and the main package. Underneath it sit AtomUI.Core, which holds the core infrastructure of the theme system, the token system and the animations, and AtomUI.Native, which is native platform infrastructure. AtomUI.Controls provides base controls and shared control capabilities, and AtomUI.Controls.Shared provides the shared interfaces and enums for control development, which is the contract layer that a third party would implement against.

Then there are the optional ones. AtomUI.Desktop.Controls.DataGrid and AtomUI.Desktop.Controls.ColorPicker are both marked opt-in, and the documentation describes a further Extras package. The guidance for users is to install the main desktop controls package first and add the optional packages such as DataGrid, ColorPicker and Extras only when the application needs them, and the examples use the latest project version.

That split is a deliberate decision about dependency weight. A desktop application that only needs forms and buttons should not pull a grid implementation and its dependencies into its output, and the presence of separate font packages and separate icon packages, with the Alibaba Sans and Alibaba PuHuiTi fonts and the shared and Ant Design icon sets, extends the same logic to assets. Icons and fonts are exactly the kind of thing that bloats a deployment, and making them opt-in keeps the base install small.

The project is distributed through NuGet, and the repository also carries a controlgallery/ directory, which is the usual name for a gallery application that exists to demonstrate every control, and a README.nuget.md for the package listing.

Theming through tokens on Avalonia's own resource system

The theming story is the most transferable idea in the project, and it is worth understanding before you commit to it.

AtomUI's theming is token-driven and built on Avalonia's style and resource system, with support for consistent customization across controls. That is a different model from hard-coding colours in styles, and it is a different model again from swapping a theme resource dictionary.

The difference is where the truth lives. With a resource dictionary swap, every control has to read its values from named resources, and the resources have to be complete and correct for every state of every control. With tokens, the values are declared once as design tokens, the tokens are mapped into Avalonia's resource system, and the controls consume the mapped resources. Changing a token then changes every control that uses it, including the ones you did not know existed, which is the entire point of the Ant Design token model.

The payoff for a team is that the design source of truth and the code source of truth are the same artefact, which is what makes a design system portable across platforms. The cost is that the token pipeline has to be part of your build, and the 6.2.6 release notes describe a generated theme-package pipeline, which is the part that got more demanding in this release.

The project also ships source generators for theme tokens, for custom controls and for localization, and the stated purpose is to reduce repetitive infrastructure code. In other words, the parts of a design system that are tedious to write by hand, the token declarations, the boilerplate for a new control, and the string resources, are generated.

The 6.2.6 release, and the breaking changes it carries

The release notes for 6.2.6 are the most important section of the project description for anyone already using it, because they contain an unusually clear statement of what an upgrade costs.

The release introduces a staged startup and a generated theme-package pipeline, moves the startup Splash into AtomUI.Controls, and updates the startup and package contracts. The documentation then says it plainly: this release contains breaking startup and registration changes, and you should upgrade AtomUI packages together, rebuild generated consumers, and republish trimmed and NativeAOT applications.

Three consequences follow from that sentence. First, there is no partial upgrade. If you take a new AtomUI.Core with an old AtomUI.Desktop.Controls, the startup contract does not match, so the packages have to move as a set. Second, if your application consumes generated code, the generated output has to be rebuilt after the upgrade rather than reused, which means the generator output is part of your build and not a checked-in convenience. Third, if you ship a trimmed or NativeAOT build, that artefact has to be produced again, because the new startup and registration path changes what the trimming has to keep.

The rest of the release is ordinary maintenance, and ordinary maintenance is a good sign: Cascader keyboard and focus fixes, control layout and hit-testing fixes, startup performance improvements, and compatibility with Avalonia 12.1.4.

The project is direct about how to prepare. It asks you to review the 6.2.6 API migration guide at docs/releases/6.2.6-api-changes.md before upgrading, and to see the CHANGELOG.md. Having a per-release migration guide, and pointing at it from the release notes, is what a component library with breaking changes should do.

The requirements floor: .NET 10 and Avalonia 12.1.4

The requirements are listed in three lines, and the first one is the one that will decide whether you can use the project at all.

The .NET 10 SDK is required, and the documentation is specific about why: the .NET 10 SDK is required to build the AtomUI MSBuild integration. That integration is what wires the source generators, the token pipeline and the theme package generation into your build, so the requirement is not a policy choice but a consequence of how the project compiles.

Then Avalonia 12.1.4, and the 6.2.6 release notes mention Avalonia 12.1.4 compatibility, so the version is pinned to a specific release of the UI framework rather than a minimum. And then Windows, macOS and Linux, with a shared .NET and XAML development model, which is the pitch: one codebase, one set of controls, three desktop platforms.

The last point deserves a note of caution rather than enthusiasm. Cross-platform in Avalonia means your code is portable, and the platform differences live in the rendering, the input handling and the native integration, which is why a package called AtomUI.Native exists at all. Native window integration is one of the things the project says it includes, and it is also where the behaviour differences between the three platforms are most likely to show up.

The repository structure supports the reading that this is a serious, long-lived project rather than a weekend port: a solution file in the newer slnx format, Directory.Build.props and Directory.Build.targets for shared build configuration, Directory.Packages.props for central package version management, a global.json pinning the SDK, separate tests/, tools/, build/ and scripts/ directories, a CHANGELOG.md with a Chinese counterpart, and both .agents/ and .claude/ directories for tooling instructions.

Licence, governance and where AtomUI is the wrong choice

The licence is LGPL-3.0, recorded in the repository and in the LICENSE file, and it is the right shape for a component library: you can use it in a proprietary application, and if you modify the library itself you have to publish those modifications. A desktop application built on AtomUI does not have to be open source.

The governance is worth noting. The project records its incubation support from the Tongming Lake Center, and it maintains a Chinese and an English README, a Chinese and an English changelog, and a Chinese and an English code of conduct, with a Telegram, WhatsApp, WeChat and QQ community presence. That is the profile of a project with a substantial Chinese-speaking user base, and it is also the reason the English documentation exists at all.

Where AtomUI is the wrong choice is a matter of expectations. It is a port of Ant Design 6, so its control set, its interaction patterns and its visual language follow that design system. If your application needs desktop-native behaviours that Ant Design does not model, a native-feeling platform control set is a better fit, and this project will not give you that without forking it. If you are on an Avalonia version older than 12.1.4, or on a .NET version older than 10, the project does not target you at all.

There is also the ordinary question of whether you need a design system at all. For a small internal utility with a dozen screens, pulling a full component system and its token pipeline into the build is a larger commitment than writing the three controls you need.

The decisive question is whether your team already thinks in Ant Design terms. If the answer is yes, AtomUI gives you that language on the desktop for the cost of a coordinated upgrade every time the startup contract changes. If the answer is no, the tokens are a burden rather than an asset, and a plain Avalonia control set will serve you better.

Editorial conclusion

Adopt AtomUI if you are building an enterprise-style Avalonia application and want an Ant Design look with a token-based theme model rather than hand-built styles, and if you are prepared to upgrade all AtomUI packages together when the startup contract changes. Do not adopt it if your app needs something Ant Design does not model, since the control set follows that design language rather than the desktop platform conventions, and do not adopt it on an Avalonia version older than 12.1.4. Before you upgrade to 6.2.6, read docs/releases/6.2.6-api-changes.md, rebuild the generated consumers in your solution, and re-publish any trimmed or NativeAOT build.

Frequently asked questions

Official sources

1. AtomUI/AtomUI on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases