If you’re building apps using Xcode 26 beta on macOS 26 beta, you should beware of the combination of their third betas. If you’re unlucky like me, you’ll discover those shiny new app icons generated by Icon Composer no longer work on any older version of macOS. This is mentioned in the Xcode 26 b3 release notes, and the workaround given is “none”.

Problem

I’ve built over 20 apps now using Icon Composer’s new icon files, with Xcode 26 b2 on macOS 26 b2. All look good in Tahoe and in previous versions of macOS, at least in Sonoma and Sequoia.

Today I built my first apps using icon files already generated by Icon Composer, but this time with Xcode 26 b3 on macOS 26 b3. In every case, I got a build warning that Xcode “failed to generate flattened icon stack for icon named…”. Although the app icon displays fine in macOS 26 b3, when moved across to Sequoia there’s just a generic icon. Inspecting the app bundle reveals that there’s no icns file inside. The Xcode warning implied this might be related to CoreSVG.

Workaround

I next tried building the same projects using Xcode 26 b2 on macOS 26 b3, but that made no difference at all.

What does appear to be effective is to build in Xcode 26 b2 on macOS 15.5. So far each of the apps I’m trying to build has then worked fine in both Tahoe and Sequoia, and that magic icns file is back.

I wish you success.

Summer is an unpredictable time of year. With the Atlantic hurricane season already upon us, we could see searing heat or devastating storms. So it is with the announcements made at WWDC earlier this month: do we have time to try out some of the new features coming in three months, or must we get on with wrangling deprecations and changes looming in macOS Tahoe?

A glance through Apple’s beta release notes might suggest it should prove innocuous, and the great majority of code that’s already happy in Sequoia should have no problems in Tahoe, and so far that’s my experience. That should leave us plenty of time to adjust our app icons so they display properly in the Dock and elsewhere, but it’s there it gets more subtly complicated.

Fix app icons

I don’t think I can over-stress the importance of using Icon Composer for creating replacement app icons. If you don’t, then Tahoe seems determined to deface many traditional icons so they become almost illegible and unusable. The only exemptions are those already conforming to the fixed outline of a square with rounded corners. Any irregularity such as putting a pixel outside that, and they’re relegated to the sin bin.

Here are two icons for the same app viewed in Tahoe. The left one uses a traditional AppIcon.icns icon image, while that on the right is the same circular PNG that has been applied using Icon Composer and added as a .icon file. So far my attempts to get this to work using Xcode 16.4 have been unsuccessful, and the only solution has been to use a beta-release of Xcode 26.

Overhaul controls

That brings with it another problem, as it automatically converts AppKit and SwiftUI layouts so they use Tahoe’s new interface style, and that can generate further work. If you look closely at Apple’s demos of Tahoe at WWDC, you may notice that its controls have changed in size and shape. Not only do most have more rounded corners, but they also have different dimensions.

Interface conversion for apps that use AppKit or SwiftUI is clever, as it preserves the original for use in previous versions of macOS, and only adopts the new style when in Tahoe. Build your app with its smart new Tahoe-compatible icon and run it in Sequoia, and it looks just the same as it did.

This demo, Mallyshag, looks the same in Sequoia, but has become a mess in Tahoe because of those changed control dimensions.

Those three buttons are significantly wider, so now overlap one another and are wider than the text box below. They need a careful overhaul before they’re ready for Tahoe. Conversion can also have unexpected side-effects: for example, I’ve had some selectable text fields changed to be editable as well. You can see an example that I missed in the left view in XProCheck’s window. I now check carefully through every detail in windows that have been migrated by Xcode to support Tahoe.

This doesn’t just apply to AppKit windows in Interface Builder. Although SwiftUI dynamically positions controls, I’ve found it necessary to increase the minimum width of some views to ensure they remain fully usable.

Aside from any code changes needed, migrating an app to Tahoe thus requires:

• creation of a new app icon using Icon Composer;
• adding the .icon file to the Xcode project and setting it as the app icon;
• careful checking and rectification of all windows and their contents.

NSLog

There’s one last thing that may have escaped your attention in Apple’s release notes: NSLog. When Apple introduced the Unified log in macOS Sierra, it preserved the longstanding use of NSLog as a means of making entries with a minimum of fuss. More formal methods are more cumbersome, although they’re also more powerful, so NSLog still remains popular with developers, at least until Tahoe’s change.

A long way down the release notes, and oddly announced under the subheading of New Features, Apple states that NSLog will no longer record anything of use in its entries in the Unified log, although they’ll still be reported in full in Xcode and to stdout. One of the other purposes of my test app Mallyshag was to verify just what is now recorded by NSLog.

This is the entry obtained using LogUI when running either version of the app in macOS 15.5:

And this is the extent of entries seen in macOS 26:

So what in earlier macOS might have been a useful
Error number 1467296 in Mallyshag
is redacted to the contentless stub <private>.

If you still use NSLog, you’ll almost certainly want to move on to a better alternative, again being careful to avoid ending up with its contents redacted.

Outcomes

Come the release of macOS 26 Tahoe, there’ll be three groups of apps:

• those that haven’t been ported at all, whose icons will be almost unrecognisable;
• those whose icons display correctly, but with flaws in interface controls;
• those that work as expected, with conformant icons and controls.

Some will also write dysfunctional messages in the log, because they’re still using NSLog, although few users are likely to notice that.

That doesn’t take into account those apps relying on alternatives to AppKit and SwiftUI for their interface, as those have a great deal of ground to cover in just a few months if they’re going to be ready in time for Tahoe’s release.

That’s why I’ve started unusually early in getting my apps ready for the autumn/fall. I’m sure that summer still has some surprises in store.

Mallyshag?

This is a local Isle of Wight name for a caterpillar, usually a large and hairy one. It just seemed appropriate.

In addition to its rounded corners and Liquid Glass, macOS 26 Tahoe brings substantial change in app icons. These follow the move to squares with rounded corners brought in macOS 11 Big Sur, and now enforce that outline on all apps, including Apple’s. The result is that icons of irregular shape, such as those used by SilentKnight and the rest of my apps, will be intentionally shamed by reduction in size and placement in a sin bin of a grey square with rounded corners. Although some developers are busy implementing workarounds, Apple has made it clear that it expects conformity with this new style.

While app designers and developers have to work within those stricter constraints, Tahoe opens up new user options in the display of app icons, extending the light and dark appearances that have been standard since macOS Mojave seven years ago. System Settings now provide a choice of four rendering modes for the display of icons and widgets, in dark, clear, tinted and default, with a further option for tinting colour.

To accommodate these changes, Tahoe has a new app aimed at those designing and implementing app icons, Icon Composer, free for anyone to download from here, and compatible with macOS Sequoia and later. Although not intended for customising icons within existing apps, it provides insight into these new design constraints and rendering modes.

In the past, app icons have been able to distinguish themselves by their form, colour and internal details, with the first two becoming dominant as their size is reduced in a heavily loaded Dock. By enforcing a uniform outline, Apple’s new interface style makes this task harder. I already have difficulty distinguishing Messages, FaceTime, even Numbers and Archive Utility, which in turn forces me to separate them in the Dock, and I still occasionally open the wrong app as a result. Other confusions have become common: Xcode, Developer and several third-party app icons are also hard to distinguish when at small size. Apple clearly hasn’t listened to criticism from users and developers, and has only made this worse in Tahoe.

We’re therefore left to make the best we can within these new rules. My recent redesigns for my own apps are an initial attempt to make their icons as distinct as I can, and to remain so in older versions of macOS at the same time.

I’ll start with the new icons for Mints, SilentKnight and SystHist, seen in the Dock in existing macOS in light mode.

and dark mode

Here, with the addition of XProCheck, are four of the many possibilities in Tahoe, first in light mode with default rendering

then in dark mode, again with default rendering

Clear rendering decolourises them into monochrome with valuable contrast

but tinted rendering makes their details even harder to read

As I gain experience in using Icon Composer, and understand better how Liquid Glass may be able to enhance the results, I intend improving on these. For the time being, though, what you see in these updated versions works better across all recent versions of macOS and Tahoe. As with other features of macOS 26, these will take further tuning on my part, and patience on yours. Please bear with me in the coming weeks and months.