Add support for Composer Icons

[paulober]

Add support for Icon Composer (.icon) app icons

This adds support for Xcode Icon Composer based .icon folders introduced in macOS 26 Tahoe's Liquid Glass design system (see #24132).

Changes

• Recognize .icon folders: Treats .icon directories as asset catalogs alongside .xcassets
• "Process"/Detect icon.json files: Handles icon.json metadata files in addition to Contents.json
• Enable --app-icon flag: .icon-based icons now pass validation and get the --app-icon flag passed to actool
• Support alternate icons: Works with IncludeAllAppIcons for runtime icon switching

Background

The new .icon format is a folder structure containing:

• icon.json - Icon metadata (layers, materials, effects)
• Assets/ subfolder - Vector graphics and image assets

This replaces static .icns files to support Liquid Glass features like translucency, specular lighting, and cross-platform rendering.

Usage

Add .icon folders to your project:

<ItemGroup>
  <ImageAsset Include="Resources\AppIcon.icon\**" />
</ItemGroup>

<PropertyGroup>
  <!-- Optional: Specify which icon to use -->
  <AppIcon>AppIcon</AppIcon>
  
  <!-- Optional: Include all icons for runtime switching -->
  <IncludeAllAppIcons>true</IncludeAllAppIcons>
</PropertyGroup>

The build system will:

1. Recognize the .icon folder as a valid app icon
2. Pass it to actool with the --app-icon AppIcon flag
3. Compile it into Assets.car

Testing

I could not figure out based on the docs how to get it installed locally to test it with my MAUI app. Advices would be appreciated.

[paulober]

@dotnet-policy-service agree

[rolfbjarne]

I could not figure out based on the docs how to get it installed locally to test it with my MAUI app. Advices would be appreciated.

Were you able to build the repository locally?

If so, the easiest way is to build your MAUI app using the local build by executing dotnet from the checkout:

cd /path/to/dotnet/macios

# build macios
make all -j8 && make install -j9 

# install the MAUI workload
dotnet workload install maui-ios --skip-manifest-update

# build your project
dotnet build /path/to/your/maui-project.csproj

If you could also add an .icon resource to this test project:

https://github.com/dotnet/macios/tree/main/tests/dotnet/AppWithXCAssets

that would be great!

[rolfbjarne]

It doesn't work on tvOS?

[paulober]

It should work on tvOS I just forget to add it

[dotnet-policy-service]

Hi @@paulober. Due to inactivity, we will close this pull request in 7 days.

[rolfbjarne]

Continued in #24722.

[paulober]

Hi @@paulober. Due to inactivity, we will close this pull request in 7 days.

Sorry, did not have the time to continue working on this at the moment. Thanks for continuing.

In case anyone needs an immediate solution, I currently have this workaround for MAUI in-place:

<Target Name="RebuildAssetCatalogWithLiquidGlassAppIcon"
            AfterTargets="_CoreCompileImageAssets"
            BeforeTargets="_ComputeBundleResourceOutputPaths"
            Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'
                and $([System.IO.Directory]::Exists('$(ProjectDir)$(IntermediateOutputPath)$(_ActoolClonedAssets)'))
                and $([System.IO.Directory]::Exists('$(MSBuildProjectDirectory)/Platforms/iOS/AppIcon.icon'))">

        <!-- Late-bind: at this point IntermediateOutputPath is fully resolved (incl. RID/DeviceSpecific) -->
        <PropertyGroup>
            <_LiquidGlassAppIconName>AppIcon</_LiquidGlassAppIconName>

            <_ActoolRoot>$(IntermediateOutputPath)actool</_ActoolRoot>
            <_ActoolClonedAssets>$(_ActoolRoot)/cloned-assets/Assets.xcassets</_ActoolClonedAssets>
            <_ActoolBundleOut>$(_ActoolRoot)/bundle</_ActoolBundleOut>
            <_ActoolPartialPlist>$(_ActoolRoot)/partial-info.plist</_ActoolPartialPlist>

            <_LiquidGlassIconBundle>$(MSBuildProjectDirectory)/Platforms/iOS/AppIcon.icon</_LiquidGlassIconBundle>
            <_AssetsCar>$(_ActoolBundleOut)/Assets.car</_AssetsCar>
        </PropertyGroup>

        <!-- Only run if MAUI already generated the cloned asset catalog -->
        <Message Importance="high"
                 Condition="$([System.IO.Directory]::Exists('$(_ActoolClonedAssets)'))"
                 Text="Rebuilding Assets.car (With Composer Icon) | IOP=$(IntermediateOutputPath) | actoolRoot=$(_ActoolRoot)" />

        <Error Condition="!$([System.IO.Directory]::Exists('$(_ActoolClonedAssets)'))"
               Text="actool cloned asset catalog not found: $(_ActoolClonedAssets). Make sure _CoreCompileImageAssets ran and produced the intermediate actool folder." />

        <!-- Ensure output exists (actool will fail otherwise) -->
        <MakeDir Directories="$(_ActoolBundleOut)" />

        <!-- delete the previously generated Assets.car so we KNOW we replaced it -->
        <Delete Files="$(_AssetsCar)" ContinueOnError="true" />

        <!-- rerun actool with the same essential args MAUI uses, plus app-icon flags -->
        <Exec Command="/usr/bin/xcrun actool &quot;$(_LiquidGlassIconBundle)&quot; --errors --warnings --notices --output-format xml1 --compress-pngs --target-device iphone --target-device ipad --minimum-deployment-target $(SupportedOSPlatformVersion) --platform iphoneos --include-all-app-icons --app-icon $(_LiquidGlassAppIconName) --output-partial-info-plist &quot;$(_ActoolPartialPlist)&quot; --compile &quot;$(_ActoolBundleOut)&quot; &quot;$(_ActoolClonedAssets)&quot;" />

        <!-- sanity check: fail fast if actool didn't produce Assets.car -->
        <Error Condition="!Exists('$(_AssetsCar)')"
               Text="Actool rebuild did not produce Assets.car at $(_AssetsCar)" />
    </Target>