TL;DR Apple has introduced a new layered approach to app icons in iOS and macOS 26. This post explains how to update your .NET and MAUI app icons to comply with the new requirements and ensure your app looks great on all devices. I outline two different approaches from easiest (do nothing) to hardest (composing and compiling your icons). I also outline the steps needed to manually compile your icons using the actool command line tool.

The New Icon Requirements

With the release of iOS and macOS 26, Apple has introduced a new way to handle app icons. Instead of using a single static image, developers can now create layered icons that adapt to different contexts and styles.

All icons are now rounded rectangles with a required background layer and then up to four additional layers on top. These layers can each have their own material properties such as specularity (shininess), transparency (along with frosting), and drop shadows. Each layer is treated as being physically above the previous layer, creating a variety of 3D effects.

The layers are composited by the OS to create the final icon, which dynamically adapts to the environment, and, more importantly, user settings.

So how do you take advantage of this new feature in your .NET and MAUI apps? I’ll give you 3 options from easiest to hardest.

Option 1: Do Nothing

The easiest option is to do nothing. If you don’t update your app icons, Apple will analyze your icon and automatically create a layered version for you. This is the easiest option, but it may not give you the best results.

Simple Icons

This approach works well if your icon is a typical two-layer icon with a background and some distinct foreground imagery. In this case, Apple will attempt to separate the background and foreground layers and apply some default material properties to each layer.

For example, here is a simple icon with a blue background and white foreground and a little drop shadow. To its right is the automatically generated layered icon.

Simple Icon Compare

Note that the corners are rounded and the system applied specular highlights to the border. The drop shadow and the gradient background were preserved.

If your icon is simple like this, you can probably get away with doing nothing. You’ll miss out on the 3D layering effects, but your icon will still look good and will fit in with the OS.

What if your icon is more complex?

Complex Icons

Complex icons, those that use transparency to create a non-rectangular shape, do not fare as well with the automatic approach. The system will add a background layer of its own choosing (some shade of gray) and then place your icon on top of it. This immediately distinguishes your app as older and not taking advantage of the new icon system.

Here is an example of a more complex icon with transparency and multiple colors.

Complex Icon Compare

In this case, the system added a gray background layer and then squeezed the original icon on top of it. The result is a bit jarring and does not fit in with the new icon style.

If your icon is complex like this, then you should consider fully redesigning your icon using the new layered approach and Icon Composer app.

Option 2: Use Icon Composer

The Icon Composer app is a new tool included with Xcode 26 that allows you to create layered app icons. You can use this tool to design your icon with a background and up to four foreground layers, each with its own material properties.

To use it, you will want to start with your original icon and decompose it into layers. Ignore the background layer as that will be configured in the Icon Composer app. Then, create up to four additional layers for the foreground elements of your icon.

These layers should be simple SVG or PNG files without drop shadows, transparency, or too much highlighting since those attributes can be configured in the Icon Composer app itself.

Let’s see it in action. First, I extracted the foreground layer and exported it as a PNG file. I then created a new icon in Icon Composer with a background gradient and this simple foreground layer.

Icon Composer

On the left is my single layer (with transparency) and on the right is the rendered icon (on macOS). There is the background gradient shaded a bit differently than before (I used the same colors from the other examples, the difference is due to the system’s rendering lighting model). The foreground layer is now sitting on top of the background with a very light drop shadow.

Most striking is how the foreground now gets rendered with its own specular highlights and shading. It looks quite rounded now. These are just the defaults, within Icon Composer you can adjust the material properties of each layer to get the look you want.

Here is a screenshot of the Icon Composer app itself so you can see the layers and properties.

Icon Composer App

There are a lot of options and even more environments (dark, light, mac, iOS, tinted, etc.) to preview your icon in.

Manually Compiling Your Icons

As of this writing (September 12, 2025), the .NET build system does not handle the new layered icon format.

However, you can manually compile your icons using the actool command line tool that comes with Xcode. This tool will take your .icon file created with Icon Composer and produce (1) a compiled Assets.car file that contains the layered icon for macOS 26 and iOS 26, and (2) a backwards compatible .icns file for macOS that will be used on older versions of macOS. This tool needs to be run separately for iOS and macOS.

This process is quite hacky, so I’d recommend waiting until the .NET build system supports this natively. But if you want to try it out, here are the steps.

iOS

# Compile for iOS
/Applications/Xcode.app/Contents/Developer/usr/bin/actool \
    MyApp/MyIcon.icon --app-icon MyIcon \
    --compile . \
    --output-partial-info-plist assetcatalog_generated_info.plist \
    --target-device iphone --target-device ipad --minimum-deployment-target 13.0 --platform iphoneos \

This will produce 4 files:

  1. MyIcon60x60@2x.png - backwards compatible image for iPhones running iOS 13.0 and later
  2. MyIcon76x76@2x~ipad.png - backwards compatible image for iPads running iOS 13.0 and later
  3. Assets.car - the archived assets that contain the new fully layered icon for iOS 26 and beyond. This is the file you need to include in your app bundle as a resource for the new icon to be used.
  4. assetcatalog_generated_info.plist - a plist file whose entries you should add to your app’s Info.plist file.

If your app is using other Assets, then you should augment the command line to include the .xcassets directory. For example:

# Compile for iOS with existing assets
/Applications/Xcode-26-RC.app/Contents/Developer/usr/bin/actool \
    MyApp/Assets.xcassets \
    MyApp/MyIcon.icon --app-icon MyIcon \
    --compile . \
    --output-partial-info-plist assetcatalog_generated_info.plist \
    --target-device iphone --target-device ipad --minimum-deployment-target 13.0 --platform iphoneos \

macOS

Supporting macOS is similar, but you only need to support one target device (mac) and you will get a backwards compatible .icns file instead of multiple PNG files.

# Compile for macOS
/Applications/Xcode.app/Contents/Developer/usr/bin/actool \
    MyApp/MyIcon.icon --app-icon MyIcon \
    --compile . \
    --output-partial-info-plist assetcatalog_generated_info.plist \
    --minimum-deployment-target 11.0 --platform macosx --target-device mac

This will produce 3 files:

  1. MyIcon.icns - backwards compatible icon for macOS 11.0 and later
  2. Assets.car - the archived assets that contain the new fully layered icon for macOS 26. This is the file you need to include in your app bundle for the new icon to be used.
  3. assetcatalog_generated_info.plist - a plist file that you can ignore (just contains the icon name).

Including in Your App

Once you have the compiled Assets.car file for iOS and/or macOS, you need to include it in your app bundle as a resource (along with the .png and .icns files).

In your .csproj file, you can include the files like this:

<ItemGroup>
  <BundleResource Include="Assets.car" />
  <BundleResource Include="MyIcon.icns" Condition="'$(TargetFramework)' == 'net9.0-macos'" />
  <BundleResource Include="MyIcon.png" Condition="'$(TargetFramework)' == 'net9.0-ios'" />
</ItemGroup>

You also need to update your Info.plist file adding whatever entries were generated in the assetcatalog_generated_info.plist file.

Conclusion

Apple’s new layered app icon system in iOS and macOS 26 offers a great opportunity to make your app stand out with dynamic and visually appealing icons. You can choose to do nothing and let the system generate a layered icon for you, or you can use the Icon Composer app to create a custom layered icon. For the adventurous, you can manually compile your icons using the actool command line tool. Whichever approach you choose, updating your app icons will help ensure your app looks great on all devices and fits in with the latest design trends.