Redesign Apple Icons for new iOS/macOS 26 Standards

[patmauro]

[DRAFT PR.] Redesigns the macOS & iOS icon sets to adhere to the new Liquid Glass design language and Icon Composer asset bundle introduced in macOS/iOS 26; Effectively supersedes #1526 and #1689. The core design - which stays consistent with the template set by Cyan's Myst iOS icon - largely stays as-is, but gets a couple new optimizations that allow it to play nicer with the new design language and icon format.

One big change here is the introduction of the new Apple .icon format used by Icon Composer, which replaces the Asset Libraries previously needed for icon sources. The trade-off is that without a dedicated Asset library, we can't really optimize by size anymore, which means we effectively lose all the improvements from #1526 - but I think the trade-off is worth it in this case. This means we are no longer using the original Cyan asset here and are only leveraging our custom version, which is a hybrid of two upscale attempts by myself and @Kohtlyr. I'm OK moving forward with this, though.

Rebuilt in Layers

As part of the revamp, the new icon format breaks down our icon into individual layers:

• Background layer: this was already "overscanned" to get us to the square target in the original, so we had plenty of room to expand this out to the 1088 size needed for watchOS, and all other formats simply crop this down to the original 1024 - so that forms our initial layer. This already has kind of a glassy look and we probably could make it semi-translucent if we wanted - but I didn't really think that was necessary.
• Book Layer: One thing to note here is that for all prior versions of this icon we have been consistently baking in a drop shadow on the book designed to mimic the drop shadow from the 2007 macOS Leopard-era icon as closely as possible. But now that there is a new definition here for how layers should create shadows in Mac icons, we can offload the responsibility of generating that drop shadow to Icon Composer itself, for consistency. I was also curious if there was a way to add some specular lighting here, but as @dpogue pointed out earlier, there's kinda no way to make that look good with this particular image asset - so we'll leave it as-is here.

Variants

With those layers established, we can make our themes:

• Default: Comes out in the wash largely the same as our original, but with the new specular edges and dynamic drop shadow effect. (Below: old vs. new.)
  • 
• Dark Mode: Our Dark Mode icon for iOS 18 came out pretty good, but with some of the advantages offered by Icon Composer, I thought we could do even better here. Instead of removing the background outright, I instead took the Relto graphic, desaturated it and applied it as an overlay on top of the standard black background tile. The effect is pretty subtle and I think looks very nice. (Below: old vs. new.)
  • 
• Monochrome: There's a lot more variations to this this time compared to the iOS 18 version we built earlier, and I wasn't quite quite happy with all of them - with the old monochrome image, Clear Light and Tinted Dark just weren't really working. As I kept tweaking it became clear that if we wanted this to look good, we would probably need to play ball with the layered frosted glass approach Apple really had in mind here. So I reconstructed the book element in layers - and the result wasn't half bad! I think this is a winner, but given that this was really an experiment, I am open to feedback. I do think attempting to work in the background image may be introducing too much visual sludge. (Below: Clear Light, Clear Dark, Tinted Light, Tinted Dark.)
  • 

TODO

Right now there are a few blockers preventing this from being moved past a "Draft PR" for the time being:

• How to Build: The app needs to be told to build from this new .icon file instead of the asset library. In a standard XCode project this would be a simple matter of redirecting this in Project Settings and making sure the entry under "App Icon" matches the new .icon file - but it's a little unclear how we will correctly set this for our cmake-based project, especially since no relevant project settings node seems to show up anywhere in the Plasma project hierarchy. @colincornaby has confirmed simply adding this to Resources is not sufficient.
  • 
  • A bigger issue here is that adopting the .icon standard (and likely implementing the new icon styles introduced for iOS/macOS26 at all, even from an Asset Library) would force us to migrate our GitHub build tools to XCode26 - as outlined here, that is a bit problematic at the moment for a few reasons: GitHub Actions ending support for Intel runners #1793
• Handling for Legacy Icons: the documentation I've read on this isn't super clear about whether the new .icon format will cover all our bases and we can remove the existing /asset/ directory altogether, or if we need to leave behind a few pre-baked PNGs in an asset library in order to account for legacy builds - I have seen conflicting info here; need more info.
  • Sounds like we'll definitely want to leave an asset library behind for the time being so that the build tools have something they can fall back to. A fair question, though, is whether we want to give these legacy icons a quick refresh while we're at it. Would love to see some other examples of how devs are handling their legacy icons.
• Other Feedback: The monochrome icons in particular were a bit of an experiment, so I'd like to get some feedback on this before proceeding. The subtle background layer might be giving a little too much visual "sludge" here.
• Cleanup: I will probably want to do a final cleanup pass on the source assets and their filenames before this is ready for primetime - it's a little messy as is.

[colincornaby]

I actually really like the monochrome a lot more than I thought I would. Looks good.

Making a note for myself:

• Plasma builds with Xcode 26 on GitHub Actions to adopt new icon

[dpogue]

IIRC to use a .icon file as the app icon, you just need to include it as a resource in the Xcode project.

Xcode 26 will use a .icon file if it exists and fall back to the icon in .xcassets otherwise, so my preference would be to retain the old icons (at least for a while) for compatibility with older Xcode versions.

[dpogue]

I think the way Xcode handles the lookup is by name matching, so this might need to be named "AppIcon.icon" instead of "plClientIcon.icon" so that it matches the xcassets AppIcon.appiconset naming.

In theory, we'll be able to use this .icon file for both macOS and iOS builds too :)

[colincornaby]

IIRC to use a .icon file as the app icon, you just need to include it as a resource in the Xcode project.

Xcode 26 will use a .icon file if it exists and fall back to the icon in .xcassets otherwise, so my preference would be to retain the old icons (at least for a while) for compatibility with older Xcode versions.

Does this mean the icon just needs to be included in the bundle's resource folder? I haven't dug in to how to bundle the new icons yet.

[dpogue]

Doesn't need to be in the Resources folder from what I recall. Xcode wants you to drag it in directly under the project, and then set the file build type to be a resource.

[patmauro]

Doesn't need to be in the Resources folder from what I recall. Xcode wants you to drag it in directly under the project, and then set the file build type to be a resource.

Yeah, this is the guidance I've seen on this so far - you'd set the appropriate Target at this time as well. The latter is where it gets a little tricky here though, as this is an atypical XCode project.

[dpogue]

this is an atypical XCode project

yeah, shouldn't be hard, just need to figure out the right CMake incantations to get things in the right spot

[Deledrius]

Those all look really good to me. 👍🏼

[colincornaby]

I'll do some review tonight about how to get the new icons in - probably need to watch the Apple Developer video on it. I've been focused on stuff other than Tahoe this year so I haven't had a chance to dig into the project settings for the new icons yet.

Hopefully will have an update soon. But regardless we'll need to get the Github Actions agents building against Xcode 26 for this to work. I think we should be ready for that, we just need to update the build script.

[colincornaby]

I've added a change that should get it working. It looks like including it in the resources folder is sufficient. However - this may or may not work on Xcode 16.

The only thing I'm weirded out by here is that Apple's apps don't have the icon just floating around in their resources folder. So I might be missing something here.

[colincornaby]

I looked in to the GitHub Actions situation and they've only deployed the beta version of Xcode 26. I'm not sure what this PR would do without the new SDK. We might need to hold until the final SDK is available in actions. I don't really want to build against a beta.

[patmauro]

I looked in to the GitHub Actions situation and they've only deployed the beta version of Xcode 26. I'm not sure what this PR would do without the new SDK. We might need to hold until the final SDK is available in actions. I don't really want to build against a beta.

We can, of course, have Icon Composer generate and deploy flat PNGs of the new style to the existing Asset Library as an interim adjustment - but I don't know how valuable that would be vs. just holding off on this effort altogether until GitHub Actions has official XCode 26 support. (There's also the matter of whether the XCode 16 compiler is still going to be looking for the 100px border that no longer exists in this new style, flat or otherwise - the icons are completely rescaled to account for this, so it's an important detail.)

Still, a refresh of the asset library in the interim may not be the worst idea in the world - might be a good opportunity to merge things down for cleanliness. Either way, we'd probably be talking about a separate PR for that - better to keep this one focused on the "parent" topic. If that seems worth looking into, let me know and I'll spin up a branch.

[dpogue]

To better summarize the problem: We can move arm64 builds to a macos-26 runner (which is in beta, and kinda unreliable in my experience), but we can't move the x86_64 builds there because of build issues when cross-compiling. Which means (for now) we are stuck with an older version of Xcode for x86_64 builds, which won't know what to do with the .icon file assets.

I think it should be fine to just add the AppIcon.icon as a resource and new Xcode will use it and old Xcode will keep using the .xcassets/AppIcon.appiconset

[patmauro]

To better summarize the problem: We can move arm64 builds to a macos-26 runner (which is in beta, and kinda unreliable in my experience), but we can't move the x86_64 builds there because of build issues when cross-compiling. Which means (for now) we are stuck with an older version of Xcode for x86_64 builds, which won't know what to do with the .icon file assets.

I think it should be fine to just add the AppIcon.icon as a resource and new Xcode will use it and old Xcode will keep using the .xcassets/AppIcon.appiconset

Sure - my point was just that, despite being the main focus of this PR, there's really no rush for us to adopt the new .icon standard, as Apple has not technically deprecated asset libraries for icons, and in fact encourages their continued use for specific use cases. So regardless of the specific situation with x86_64/GitHub Actions/XCode26, there is really no harm in us taking extra time to make sure all our ducks are in a row here, if we want - in which case, doing a refresh of our existing asset library might be perfectly acceptable in the interim. So, just pointing out that we have options here, and don't need to rush adoption of this new .icon format.

As a sidenote, I agree with @Hoikas' comment in #1793 -

A pull request to add an icon should not and cannot cause us to trash support for an entire toolset.

If push comes to shove - I'd much rather we play it safe!

[colincornaby]

There's discussion both here and in #1793 about the icon - I'm going to follow up here.

I am still unsure if Xcode 26 is required here. It's possible it would be needed to create an icns for backwards compatibility - but we also have our own icns we can copy in.

Same thing is true with iOS.

I don't know if the .icon is supposed to be copied into the bundle as a resource. Apple's apps do not have an icon in their Resources directory. I'm still following up on that with other developers. But Tahoe is still new so I'm having trouble getting consensus on what the application bundle is supposed to be.

So still a lot of things I don't know - but I'm hoping to have more answers soon.

[colincornaby]

Ok, I have answers.

.icon files are not resources. They are handled by the build system as a custom stage. This custom stage is only present in the Xcode 26/Tahoe SDK. At build time the .icon is compiled into the asset catalog. This cannot be done in Xcode 16 because Xcode 16 does not know how to handle a .icon file at build time.

The nuances that @patmauro noted are correct - the icon needs to be added to the project file in a very specific way. I need to figure out how to replicate that in CMake. Adding the icon to the resources folder is not sufficient. This PR should not be accepted as is.

This also means accepting this icon would require addressing the Github runner question.

I don't know what to do with this PR - but I wouldn't be too hasty here. This is only the first issue we're going to run into by not having access to the Tahoe SDK. I think #1793 will take time to resolve - but that issue will eventually be bigger than just an icon. So I'm not feeling like the solution here is just to close this PR and ignore the Tahoe SDK problem.

If I figure out how to manipulate the CMake correctly we could always add a CMake check and only include the icon in the presence of the Tahoe SDK. We just wouldn't get this icon output from our official agent runs.

We still need to maintain compatibility with older SDKs anyway. When I test on older hardware I'm usually building against an old SDK. So having a Tahoe SDK check might be a good idea anyway.

[patmauro]

Yeah, I was aware when I first opened this that there were gonna be some pretty big problems here and this would not be ready to go as-is, but figured it would be more valuable to at least put a Draft PR together so we were better able to review some of this together - to that end it seems to have been beneficial, at least in illuminating some of the challenges here. Certainly had no intention of moving this out of Drafts and submitting for official consideration until any such issues were sufficiently addressed.

In absolutely no rush here - happy to just keep this draft PR on ice for a while. Your call if you'd be more comfortable just closing it outright and opening a new one later, but it might be beneficial to keep this around so we can continue to poke at it together. Up to you.

[patmauro]

Oh, and also -

This is only the first issue we're going to run into by not having access to the Tahoe SDK. I think #1793 will take time to resolve - but that issue will eventually be bigger than just an icon.

Yep, exactly - 100% agree. As I mentioned in #1793, even the icon is bigger than just the icon - the challenge here is less the .icon file itself and more that Tahoe now has completely different standards for how icons are handled altogether compared to Sequoia (even just with flat PNGs). I'd say it's highly unlikely this will be the only instance of new OS quirks we uncover.

[colincornaby]

I've added some new CMake that should:

• Make this icon only be included on Xcode 26 (so it's safe to deploy to our existing agents.)
• Set the file type so it gets compiled to the asset catalog correctly by the toolchain.

I think I can call set_source_files_properties even if the file is not included - but my CMake skills are not the greatest.

[dpogue]

This is currently not using Xcode 26 in CI, so if those builds are passing it seems like this should be fine.

[dpogue]

This appears to do all the right things, except it doesn't set the target membership of AppIcon.icon to plClient.

I'm somewhat unconvinced that just adding it as a resource won't do the right thing. I've used that method in an iOS project and it seems to be doing the right thing and not bundling the .icon file itself.

[colincornaby]

I'm somewhat unconvinced that just adding it as a resource won't do the right thing.

The issue is that CMake doesn't set the right content type when it generates the project. We have to do that explicitly until CMake is updated (and we get the updated CMake.) I took apart the pbproj to debug the issue.

[Hoikas]

This looks wrong. The source files haven't been added to the target yet, so I feel like this may not work. Worse, Mac-Cocoa/AppIcon.icon is a generator expression in the list, but this is unconditional.

[dpogue]

FWIW, I've opened a PR on CMake to teach it about the UTI for .icon files: https://gitlab.kitware.com/cmake/cmake/-/merge_requests/11259

[colincornaby]

It looks like this build failed because one of the repos providing a dependency was down.

[dpogue]

If we care to, there's an option to keep using the existing icons on macOS <26 and only use the new one on 26+: https://mastodon.social/@siracusa/115254777896289996

Name your Tahoe .icon file the same as the name of your existing .iconset in the Assets catalog and then set the ASSETCATALOG_OTHER_FLAGS build setting to --enable-icon-stack-fallback-generation=disabled

[patmauro]

If we care to, there's an option to keep using the existing icons on macOS <26 and only use the new one on 26+: https://mastodon.social/@siracusa/115254777896289996

Name your Tahoe .icon file the same as the name of your existing .iconset in the Assets catalog and then set the ASSETCATALOG_OTHER_FLAGS build setting to --enable-icon-stack-fallback-generation=disabled

The style is different enough that I was curious about this, at least in the interim. Sounds like a good idea to me.

[colincornaby]

It looks like it's building now. This is just a draft - but because these changes will only take effect on Xcode 26 and later I think we're ok. As long as we're in agreement with the look of the new icon.

[patmauro]

It looks like it's building now. This is just a draft - but because these changes will only take effect on Xcode 26 and later I think we're ok. As long as we're in agreement with the look of the new icon.

I have some final optimizations I'd like to apply (some assets are being used twice that can probably be merged, etc) but yes, pending any other feedback, if we're feeling ready to move forward with this I can pull this out of drafts once done.

[dpogue]

@colincornaby The issue that I'm seeing in Xcode 26.0.1 that I haven't managed to find a solution for is that the icon is in the right spot in the folder tree, but isn't added to the plClient target, so it never gets bundled.

The CMake code looks right for all of this, but it should be showing up in the Resources folder on the Xcode filetree (in theory, because everything listed in plClient_RESOURCES is supposed to be in there) and it's showing up in the plClient folder instead.

[dpogue]

It sounds like ASSETCATALOG_OTHER_FLAGS & --enable-icon-stack-fallback-generation=disabled no longer work in Xcode 26.1: https://mastodon.social/@siracusa/115491845898322390 😞

[colincornaby]

Thats not totally unexpected. There's a series of compatibility flags Apple added that they've been threatening to remove. I guess we'll just have to accept the new icon for all releases when we're able to build against the new SDK.

[colincornaby]

Following up on this. We've adopted the new Xcode so we can accept a new icon for Tahoe. There might be stylistic concerns here, especially if we can't keep the old icon around for older versions of macOS.

As per the previous conversation - Tahoe icons work differently, they need to be handled by the build system, they won't be included as resources like previous icon formats.