How does the system decide on NSMenuItem.ImageVisibility?

You're correct that the automatic visibility is only applied to symbol images. Non-symbol images remain visible by default, although you can still use the preferredImageVisibility property to hide them if appropriate for your application.

This behavior was chosen to provide the best compatibility with existing apps. Symbol images used for menu items are still a (relatively) new feature for macOS apps; many applications historically used non-symbol images for menu items, long before the macOS Tahoe UI recommendation to use symbol images for most or all menu items. Generally, apps using non-symbol images for menu items have made an explicit choice that those items should have visible images, and therefore AppKit keeps them visible.

I looked at the documentation page for NSMenuItemImageVisibility and you are correct; the header comments must have been incorrectly imported into the documentation and assigned to the wrong values. I'll file a bug myself to have that fixed. Thanks for pointing that out!

Regarding how to provide app images that respect the system default: I think the preferred design would be to use symbol images as much as possible (creating your own custom symbol images if necessary). Non-symbol images are still completely acceptable as long as you intend for them to be visible in all cases.

There is also some discussion of the menu item image visibility behavior in AppKit and UIKit sections of the macOS 27 release notes at https://developer.apple.com/documentation/macos-release-notes/macos-27-release-notes.

Thank you for the explanation.

I use non-symbol images for menu items when there is no suitable SF Symbol available and I instead have a named template image. To keep image visibility consistent across menu items on macOS 27, I would therefore need to explicitly set those non-symbol images to .hidden.

While that works with the current behavior, it also means opting out of future system decisions regarding .automatic. If AppKit changes the policy behind .automatic in a future release, those menu items would no longer follow the system default behavior.

It seems that a separate setting, for example .system, that applies the current system policy uniformly to all image types would avoid this ambiguity and allow applications to respect future platform changes without having to distinguish between symbol and non-symbol images.

Thanks for the suggestion. Please file a bug with this suggestion and post the feedback ID here.

Thanks a lot for the answers! Here is the feedback ID: FB23070183