Add support for Composer Icons by rolfbjarne · Pull Request #24722 · dotnet/macios

rolfbjarne · 2026-02-17T10:31:43Z

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:

Recognize the .icon folder as a valid app icon
Pass it to actool with the --app-icon AppIcon flag
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.

This is a recreation of #24476 (from @paulober), because our CI can't work with pull requests from forks.

Signed-off-by: paulober <44974737+paulober@users.noreply.github.com>

- Add .icon glob patterns to ImageAsset auto-include and BundleResource exclusion in Microsoft.Sdk.DefaultItems.template.props - Fix tvOS support: register .icon assets in both brandAssetsInAssets and imageStacksInAssets for primary/alternate icon validation - Add tvOS test case to IconFileSupport - Add tests: IconFileSupportWithIncludeAllAppIcons, IconFileSupportAsAlternateIcon, InexistentIconFile, MixedXCAssetsAndIconFile - Update DefaultCompilationIncludes.md and build-items.md documentation Fixes #24132

Add a test project that uses .icon (Xcode Icon Composer) directories instead of .xcassets for app icons. The test builds the project for all platforms and verifies that raw .icon files don't end up in the app bundle as BundleResources (they should be processed by actool).

Add a basic .xcassets directory alongside .icon in the test project so the build can succeed even when actool's icon export subprocess fails (status 255 on some systems). The test gracefully skips with Assert.Ignore when icon export is not supported.

The icon.json format used 'version'+'layers'+'filename' but the correct Icon Composer format uses 'groups' containing 'layers' with 'image-name'. The old format caused actool's icon export subprocess to fail with status 255. With the correct format, actool successfully compiles .icon files into app icons on all platforms. Also removed the Images.xcassets fallback from the test project (no longer needed) and updated the integration test to assert success instead of skipping.

Copilot

Pull request overview

Adds build- and test-level support for Xcode Icon Composer (.icon folder) app icons so they’re treated like asset catalogs and can be validated/passed through to actool as the selected AppIcon (including alternate icons).

Changes:

Update ACTool to treat .icon folders as asset catalogs and recognize icon.json alongside Contents.json.
Extend default MSBuild item globs/docs to include .icon directories as ImageAsset (and exclude them from BundleResource).
Add MSBuild task tests and a new dotnet test app/project to exercise .icon handling.

Reviewed changes

Copilot reviewed 21 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`msbuild/Xamarin.MacDev.Tasks/Tasks/ACTool.cs`	Recognizes `.icon` directories and `icon.json` so `.icon`-based AppIcon/alternate icons can pass validation and be compiled via `actool`.
`dotnet/targets/Microsoft.Sdk.DefaultItems.template.props`	Includes `.icon/**` in default `ImageAsset` globs and excludes `.icon` content from default `BundleResource` inclusion.
`dotnet/DefaultCompilationIncludes.md`	Documents default inclusion behavior for `.icon` (Icon Composer) directories.
`docs/building-apps/build-items.md`	Documents that `ImageAsset` includes both `.xcassets` and `.icon` inputs.
`tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/ACToolTaskTest.cs`	Adds task-level tests covering `.icon` validation scenarios (main icon, include-all, alternate icon, missing icon, mixed catalogs).
`tests/dotnet/UnitTests/AppIconTest.cs`	Adds a unit test project build validating `.icon` inputs are not copied as raw bundle resources.
`tests/dotnet/AppWithComposerIcon/shared.mk`	Shared make configuration for the new composer-icon test app.
`tests/dotnet/AppWithComposerIcon/shared.csproj`	Shared project settings enabling `AppIcon=AppIcon` for the new composer-icon test app.
`tests/dotnet/AppWithComposerIcon/AppDelegate.cs`	Minimal app entry point for the composer-icon test app.
`tests/dotnet/AppWithComposerIcon/iOS/Makefile`	Platform makefile for iOS composer-icon test app.
`tests/dotnet/AppWithComposerIcon/iOS/AppWithComposerIcon.csproj`	iOS target project for composer-icon test app.
`tests/dotnet/AppWithComposerIcon/iOS/Resources/AppIcon.icon/icon.json`	iOS Icon Composer metadata fixture.
`tests/dotnet/AppWithComposerIcon/iOS/Resources/AppIcon.icon/Assets/front.png`	iOS Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/iOS/Resources/AppIcon.icon/Assets/back.png`	iOS Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/tvOS/Makefile`	Platform makefile for tvOS composer-icon test app.
`tests/dotnet/AppWithComposerIcon/tvOS/AppWithComposerIcon.csproj`	tvOS target project for composer-icon test app.
`tests/dotnet/AppWithComposerIcon/tvOS/Resources/AppIcon.icon/icon.json`	tvOS Icon Composer metadata fixture.
`tests/dotnet/AppWithComposerIcon/tvOS/Resources/AppIcon.icon/Assets/front.png`	tvOS Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/tvOS/Resources/AppIcon.icon/Assets/back.png`	tvOS Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/MacCatalyst/Makefile`	Platform makefile for Mac Catalyst composer-icon test app.
`tests/dotnet/AppWithComposerIcon/MacCatalyst/AppWithComposerIcon.csproj`	Mac Catalyst target project for composer-icon test app.
`tests/dotnet/AppWithComposerIcon/MacCatalyst/Resources/AppIcon.icon/icon.json`	Mac Catalyst Icon Composer metadata fixture.
`tests/dotnet/AppWithComposerIcon/MacCatalyst/Resources/AppIcon.icon/Assets/front.png`	Mac Catalyst Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/MacCatalyst/Resources/AppIcon.icon/Assets/back.png`	Mac Catalyst Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/macOS/Makefile`	Platform makefile for macOS composer-icon test app.
`tests/dotnet/AppWithComposerIcon/macOS/AppWithComposerIcon.csproj`	macOS target project for composer-icon test app.
`tests/dotnet/AppWithComposerIcon/macOS/Resources/AppIcon.icon/icon.json`	macOS Icon Composer metadata fixture.
`tests/dotnet/AppWithComposerIcon/macOS/Resources/AppIcon.icon/Assets/front.png`	macOS Icon Composer asset fixture.
`tests/dotnet/AppWithComposerIcon/macOS/Resources/AppIcon.icon/Assets/back.png`	macOS Icon Composer asset fixture.

tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/ACToolTaskTest.cs

tests/dotnet/UnitTests/AppIconTest.cs

tests/dotnet/AppWithComposerIcon/AppDelegate.cs

vs-mobiletools-engineering-service2 · 2026-02-17T12:53:04Z

💻 [CI Build #40f00db] Tests on macOS X64 - Mac Sonoma (14) passed 💻

✅ All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent
Hash: 40f00db5ee03047a1dbb6d97d9cf0a0f4c0f8a7a [PR build]

vs-mobiletools-engineering-service2 · 2026-02-17T12:56:23Z

💻 [CI Build #40f00db] Tests on macOS M1 - Mac Monterey (12) passed 💻

✅ All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent
Hash: 40f00db5ee03047a1dbb6d97d9cf0a0f4c0f8a7a [PR build]

vs-mobiletools-engineering-service2 · 2026-02-17T12:58:06Z

💻 [CI Build #40f00db] Tests on macOS arm64 - Mac Sequoia (15) passed 💻

✅ All tests on macOS arm64 - Mac Sequoia (15) passed.

Pipeline on Agent
Hash: 40f00db5ee03047a1dbb6d97d9cf0a0f4c0f8a7a [PR build]

vs-mobiletools-engineering-service2 · 2026-02-17T12:58:19Z

💻 [CI Build #40f00db] Tests on macOS M1 - Mac Ventura (13) passed 💻

✅ All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent
Hash: 40f00db5ee03047a1dbb6d97d9cf0a0f4c0f8a7a [PR build]

vs-mobiletools-engineering-service2 · 2026-02-17T12:59:04Z

💻 [CI Build #40f00db] Tests on macOS arm64 - Mac Tahoe (26) passed 💻

✅ All tests on macOS arm64 - Mac Tahoe (26) passed.

Pipeline on Agent
Hash: 40f00db5ee03047a1dbb6d97d9cf0a0f4c0f8a7a [PR build]

rocktyt · 2026-03-05T02:41:49Z

hello, is there any way to apply this on my code before .net updates?
for example, add a post build event to call xcode's actool to recompile the .icon file and Assets.xcassets

rolfbjarne · 2026-03-05T08:28:00Z

@rocktyt someone posted a solution here: #24476 (comment)

…oser-icons

- ACToolTaskTest: Replace ad-hoc error assertions with shared AssertNoIconValidationErrors helper that checks all icon validation error patterns (E7130/E7127/E7128/E7129), not just one specific message. - AppIconTest: Add Assets.car existence assertion to ComposerIcon test, matching the pattern used by TestXCAssetsImpl. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vs-mobiletools-engineering-service2 · 2026-03-20T10:57:02Z

✅ [CI Build #c2cd21d] Build passed (Build packages) ✅

Pipeline on Agent
Hash: c2cd21da2d0e3a9846f725973cc5b19367bbabec [PR build]

vs-mobiletools-engineering-service2 · 2026-03-20T11:00:21Z

✅ [PR Build #c2cd21d] Build passed (Detect API changes) ✅

Pipeline on Agent
Hash: c2cd21da2d0e3a9846f725973cc5b19367bbabec [PR build]

vs-mobiletools-engineering-service2 · 2026-03-20T11:12:28Z

✅ API diff for current PR / commit

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: c2cd21da2d0e3a9846f725973cc5b19367bbabec [PR build]

vs-mobiletools-engineering-service2 · 2026-03-20T11:23:04Z

✅ [CI Build #c2cd21d] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: c2cd21da2d0e3a9846f725973cc5b19367bbabec [PR build]

vs-mobiletools-engineering-service2 · 2026-03-20T17:48:33Z

🚀 [CI Build #c2cd21d] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 156 tests passed 🎉

Tests counts

✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 6 tests passed. Html Report (VSDrops) Download
✅ linker: All 44 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 11 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 15 tests passed. Html Report (VSDrops) Download
✅ monotouch (macOS): All 12 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 11 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ sharpie: All 1 tests passed. Html Report (VSDrops) Download
✅ windows: All 3 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

macOS tests

✅ Tests on macOS Monterey (12): All 5 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ Tests on macOS Ventura (13): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sonoma (14): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sequoia (15): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Tahoe (26): All 5 tests passed. Html Report (VSDrops) Download

Pipeline on Agent
Hash: c2cd21da2d0e3a9846f725973cc5b19367bbabec [PR build]

paulober and others added 9 commits December 23, 2025 21:19

Add support for Composer Icons

7679b9e

Signed-off-by: paulober <44974737+paulober@users.noreply.github.com>

Fix indentation in csproj files to use tabs

c58f712

Add Makefile logic to AppWithComposerIcon test project

24c7f45

Merge remote-tracking branch 'origin/main' into support-composer-icons

99a4a0b

Merge remote-tracking branch 'origin/main' into support-composer-icons

1c1bbf4

rolfbjarne requested review from emaf and mauroa as code owners February 17, 2026 10:31

rolfbjarne requested a review from Copilot February 17, 2026 10:31

rolfbjarne added copilot community Community contribution ❤ labels Feb 17, 2026

rolfbjarne mentioned this pull request Feb 17, 2026

Add support for Composer Icons #24476

Closed

Copilot started reviewing on behalf of rolfbjarne February 17, 2026 10:32 View session

Copilot AI reviewed Feb 17, 2026

View reviewed changes

tests/msbuild/Xamarin.MacDev.Tasks.Tests/TaskTests/ACToolTaskTest.cs Outdated Show resolved Hide resolved

tests/dotnet/UnitTests/AppIconTest.cs Show resolved Hide resolved

tests/dotnet/AppWithComposerIcon/AppDelegate.cs Outdated Show resolved Hide resolved

Auto-format source code

40f00db

This comment has been minimized.

Sign in to view

dalexsoto approved these changes Feb 18, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into dev/rolf/support-comp…

8d66af7

…oser-icons

rolfbjarne marked this pull request as draft March 20, 2026 10:10

This comment has been minimized.

Sign in to view

Conversation

rolfbjarne commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add support for Icon Composer (.icon) app icons

Changes

Background

Usage

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Feb 17, 2026

💻 [CI Build #40f00db] Tests on macOS X64 - Mac Sonoma (14) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Feb 17, 2026

💻 [CI Build #40f00db] Tests on macOS M1 - Mac Monterey (12) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Feb 17, 2026

💻 [CI Build #40f00db] Tests on macOS arm64 - Mac Sequoia (15) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Feb 17, 2026

💻 [CI Build #40f00db] Tests on macOS M1 - Mac Ventura (13) passed 💻

Uh oh!

vs-mobiletools-engineering-service2 commented Feb 17, 2026

💻 [CI Build #40f00db] Tests on macOS arm64 - Mac Tahoe (26) passed 💻

Uh oh!

This comment has been minimized.

rocktyt commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rolfbjarne commented Mar 5, 2026

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 20, 2026

✅ [CI Build #c2cd21d] Build passed (Build packages) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 20, 2026

✅ [PR Build #c2cd21d] Build passed (Detect API changes) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 20, 2026

✅ API diff for current PR / commit

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

vs-mobiletools-engineering-service2 commented Mar 20, 2026

✅ [CI Build #c2cd21d] Build passed (Build macOS tests) ✅

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Mar 20, 2026

🚀 [CI Build #c2cd21d] Test results 🚀

Test results

Tests counts

macOS tests

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

rolfbjarne commented Feb 17, 2026 •

edited

Loading

rocktyt commented Mar 5, 2026 •

edited

Loading