To run any app in Dark Mode, you must to be running macOS Mojave 10.14 or greater. By default, all existing apps will run in Light Mode even if the system is configured to run in Dark Mode. An app that is launched on macOS Mojave will run in Dark Mode when two criteria are met:
The system considers the app to be compatible with Dark Mode
The running application’s appearance is set to Dark Aqua
An app’s compatibility with Dark Mode is determined by a combination of the SDK it was built against, and the value of the “NSRequiresAquaSystemAppearance” Info.plist key. If your app is built against the 10.14 SDK or later, it will be considered compatible unless the key is set to YES. If your app is built against the 10.13 SDK or earlier, it is considered incompatible unless the Info.plist key is set to NO.
When a compatible app is launched, its appearance is set to match the user’s system-wide preference, as selected in the System Preferences “General” tab. To streamline development, Apple also provides a switch in Xcode itself so that the appearance of a running app can be switched on the fly without affecting the appearance of other apps running on your Mac.
Although the Xcode switch is handy for making quick comparisons between modes, there is not, as far as I know, any mechanism to always launch an app from Xcode in Dark Mode when the system is in Light Mode, or vice-versa. If you strongly prefer one mode over the other, you may want to build in affordances to your app that support debugging in “the other mode” when you need to. For example, in the build settings for your app, find “Other Swift Flags,” and add “-DDEBUG_DARK_AQUA”:
Then, somewhere early in your app’s launch, you can conditionally force the appearance if specified:
The first trick to tackling any new challenge is getting your technical references sorted. My advice to all developers is to watch the pertinent WWDC sessions, read the high-level documentation, and to immerse oneself in the Dark Mode aesthetic by perusing other applications that support it:
It goes without saying that every Mac developer should watch What’s New in Cocoa for macOS. This is always a great overview that touches on the major changes to follow up on in other sessions. For Dark Mode in particular, be sure to watch both the Introducing Dark Mode and Advanced Dark Mode sessions. These include a lot of excellent advice about both high-level design considerations and low-level practical uses of the NSAppearance API.
Although dark interfaces are nothing new, Apple’s official take on it with macOS Mojave establishes specific aesthetic choices. You’ll want to become acquainted with the decisions Apple has made so you can make the right call in your own app. I recommend switching your macOS Mojave Mac to Dark Mode and running as many apps as possible in Dark Mode to get a sense for the prevailing aesthetics.
The vast majority of Apple’s own apps have been tastefully adapted, and a growing number of 3rd party titles are listed on the Mac App Store as Apps That Look Great in Dark Mode. I’m honored that one of my own apps, MarsEdit, is listed there.
I spent a good part of the summer learning about macOS Mojave’s new Dark Mode theme, and how Mac apps can support the theme both in technical and practical ways. I adapted MarsEdit, Black Ink, FlexTime, and FastScripts to the new interface style.
During that process, I learned a lot about where to look for advice, and how to handle common scenarios. I’d like to share that advice with folks who have yet to undertake this work.
The gist of what I have to share comes from tackling challenge after challenge in my own apps. Some interfaces adapted effortlessly to Dark Mode, some needed only a little finessing, while others demanded relatively hard-core infrastructural changes.
My advice will focus on the dichotomy of Light Mode and Dark Mode. The Mac’s appearance support is more nuanced than that. NSAppearance supports a hierarchy of appearances that build upon one another. The light and dark modes are the two most prominent user-facing examples, but variations such as high contrast modes should also be considered.
These articles are loosely organized in order from more fundamental to more arcane, with a priority on establishing knowledge and techniques in earlier articles that you may need to reference in later articles. Feel free to jump around if you’re looking for something special:
Sometimes when I’m searching a GitHub repository, I end up with a ton of uninteresting results because there are, for example, tests or documentation in the repository that are not pertinent to what I’m searching for.
For example, in the Apple Swift repository, searching for “struct String” currently yields 22 results, many of which are in the “test/” subdirectory. I’m not interested in these at the moment.
To search any subpath, just modify the search with the “path:” flag: “struct String” path:/stdlib. Six results, all pertinent to the actual implementation of “struct String”. Just what I was looking for.
There are lots of fancy constraints you can apply to GitHub searches, I simply hadn’t thought to look them up until now. Maybe some of them will make your exploration easier, too.