Icon Composer: Any way to add icons to the app bundle for older macOS versions?

Question

Created 2w

Replies 3

Boosts 8

Participants 1

Several app developers are struggling with the inability to provide a separate app icons that looks nice on older macOS versions while at the same time provide Icon Composer icons that look great on macOS Tahoe 26. An ability to provide separate icons is super important to those who have app icons that follow the curvature of the default icon borders (as the corner rounding radius is different for Sequia and Tahoe). Take a look at this for example:

https://github.com/ghostty-org/ghostty/issues/7564#issuecomment-3042061547

Question: Is there a definitive/recommended way to address this issue? How can a developer add a glass icon variant that looks good on Tahoe and provide a bitmap icon for older macOS versions?

Some background info:

Prior to Xcode 26 beta 4, one could add an App Icon to Assets to be used as app icon for legacy macOS versions (Sequia and older) and use a new Icon Composer icon (placed in the project root) for macOS Tahoe 26. Enabling "Include all app icon assets" under target settings ensured that older macOS versions would use the old app icons while Tahoe the new Icon Composer glass one.

Since Xcode beta 4 this technique no longer works. Xcode instead insists on populating Assets.car with Icon Composer generated variants, disregarding the App Icon provided in Assets. Although the App Icon in Assets makes its way to a .incs file in the app bundle's Contents/Resources folder, but that is not used by macOS anymore and is there for some compatibility purposes. The Assets.car file (which matters) only contains the variants generated by Icon Composer and does not contain the png icons provided in the Assets.

Boost

Answer 1

Steve4442 OP

2w

Ok, I did some digging. According to assetutil it seems like Assets.car contains an iconstack that has all the vector layers, color data etc for the glass icon and the traditional MultiSized Image with all the icon size variants for legacy macOS versions. In beta3 however (probably due to a bug) the MultiSized image variants were not created based on the Icon Composer image (only a single 1024x1024 variant was created). This gave way for the .incs file compiled into the app root to be taken as icon image on legacy macOS versions, which feeds from the proper xcassets icon file provided by the developer, not the Icon Composer generated pngs.

In beta4 this was "fixed", so now all size variants 16x16, 32x32...512x512 variants of the Icon Composer based MultiSize Image items are compiled into the Assets.car file - so macOS takes these now. Sadly there is no way to somehow replace these variants with the proper, developer supplied image or remove them (so the .incs file could be taken by legacy macOS versions instead) - the only tool assetutil that is given to manipulate .car files is extremely limited.

I really hope Apple will fix this. I don't see why it would be beneficial to entirely disregard the developer supplied App Icon asset and instead render (somewhat oddly looking) variants based on Icon Composer icons meant for glass (it should happen only if the developer does not provide custom App Icons suitable for older macOS versions).

An alternate solution would be to improve Icon Composer so it could take icon composition variants for legacy OS versions and the developer (so instead of only "watchOS" and "iOS/macOS" these should be a third "legacy iOS/macOS" option). This could at least enable developers to supply vector and bitmap images that match the legacy icon size/corner rounding. Also there should be a preview option in Icon Composer how the icon would look on older OS versions - the way that Icon Composer now "silently" produces entirely different looking variants for macOS 15 without a developer using Tahoe ever even seeing how it actually looks like is clearly not the right way to go.

1

Answer 2

Steve4442 OP

2w

Note: I also added an issue about it in case an Apple Developer would kindly look into it and give directions on how to get around this limitation:

FB19118531

Thank you!

2

Answer 3

Steve4442 OP

2d

I received a note to FB19118531 saying Apple Engineers will look into the issue.

In Xcode 26 beta 5 there is a slight change - now the .incs file also has the icon composer generated icon (under Resources in the app bundle) with the wrong corner radius (that matches older macOS versions), making any icon that relies on the proper corner radius look bad. This means that the developer supplied Assets app icons are entirely disregarded.

I still feel that either if the developer supplies a legacy App Icon, it should be used for older macOS versions both for the .incs file and Assets.car. Or at least have the option to have the icon composer generate icons with the new corner radius even for older macOS versions (imho that does not look out of place as older macOS versions had icons in all kinds of shapes - obviously for iOS this is not a viable solution).

2