If you’re using a web view the way a browser does, to show arbitrary content from the web, then you probably don’t need to do anything special to accommodate Dark Mode. If Dark Mode takes off then maybe we’ll see some kind of CSS standard around presenting web sites for dark presentations, but for the time being users expect web pages to look … like web pages.

On the other hand if you’re using web views to support an otherwise native Mac user interface, you’ll want to do something to adapt the default styling of your web content to look appropriate in Dark Mode. For example, I use a web view in my standard about box window. Here’s how it looked in MarsEdit before I adapted any web content to Dark Mode:

The two-tone look is kind of cool, but too much of an assault on the eyes for anybody who has really settled into Dark Mode. This content is not like a web page. It’s implemented in HTML to make features such as styling, layout, and links easier to manage, but as far as users are concerned it’s an innate part of this native About Box window.

I’ve seen a few approaches to adapting web content to Dark Mode, but most of them relied too heavily on modifying the actual HTML content that was being shown. In my apps, I use web views in several places and, rather than have to jump through hoops in each place to finesse the content for Dark Mode, I thought it would be better if I could come up with a common infrastructure that all web content presenters could use without typically being concerned about appearance.

Because my app is using both legacy WebView and modern WKWebView, I had to duplicate my efforts to some extent, but for the purposes of this article I’m going to focus on the approach I took for WKWebView.

My solution is rooted in arranging for a web view to call a pertinent JavaScript function when the effective appearance changes. Because WKWebView instances are notified via the viewDidChangeEffectiveAppearance method, I decided to subclass WKWebView to fulfill this contract on behalf of clients:

class RSAppearanceSensitiveWKWebView: WKWebView {

   var didInitialize = false

   // Override designated initializers to record when we're
   // done initializing, and avoid evaluating JS until we're done.

   override init(frame: CGRect, configuration: WKWebViewConfiguration) {
      super.init(frame: frame, configuration: configuration)
      didInitialize = true
   }

   required init?(coder: NSCoder) {
      super.init(coder: coder)
      didInitialize = true
   }

   public func updateContentForEffectiveAppearance() {
      // Don't try updating anything until we're done loading
      if didInitialize && self.isLoading == false {
         let funcName: String
         if self.effectiveAppearance.isDarkMode {
            funcName = "switchToDarkMode"
         }
         else {
            funcName = "switchToLightMode"
         }

         // Call the named function only if it is implemented
         let switchScript = "if (typeof(\(funcName)) == 'function') { \(funcName)(); }"
         self.evaluateJavaScript(switchScript)
      }
   }

   override func viewDidChangeEffectiveAppearance() {
      self.updateContentForEffectiveAppearance()
      if #available(macOS 10.14, *) {
         super.viewDidChangeEffectiveAppearance()
      }
   }
}

Instances of this subclass enjoy the benefit of two JavaScript functions, switchToDarkMode() and switchToLightMode(), being called whenever the view’s effective appearance changes. In case a client doesn’t wish the content to be adapted to Dark Mode, they can simply omit the functions from the content they load into the view.

Because I don’t want to duplicate efforts to handle appearance switching throughout my apps, I implemented basic support for mode switching in my centralized “web content display” class, RSWebContentViewController. This controller takes advantage of WKWebView’s support for injecting JavaScript, to add support for switching modes to whatever content the client provided:

let appearanceModeScriptSource = """
   var darkModeStylesNodeID = "darkModeStyles";

   function addStyleString(str, nodeID) {
      var node = document.createElement('style');
      node.id = nodeID;
      node.innerHTML = str;

      // Insert to HEAD before all others, so it will serve as a default, all other
      // specificity rules being equal. This allows clients to provide their own
      // high level body {} rules for example, and supersede ours.
      document.head.insertBefore(node, document.head.firstElementChild);
   }

   // For dark mode we impose CSS rules to fine-tune our styles for dark
   function switchToDarkMode() {
      var darkModeStyleElement = document.getElementById(darkModeStylesNodeID);
      if (darkModeStyleElement == null) {
         var darkModeStyles = "body { color: #d2d2d2; background-color: #2d2d2d; } body a:link { color: #4490e2; }";
         addStyleString(darkModeStyles, darkModeStylesNodeID);
      }
   }

   // For light mode we simply remove the dark mode styles to revert to default colors
   function switchToLightMode() {
      var darkModeStyleElement = document.getElementById(darkModeStylesNodeID);
      if (darkModeStyleElement != null) {
         darkModeStyleElement.parentElement.removeChild(darkModeStyleElement);
      }
   }
"""

let appearanceModeScript = WKUserScript(source: appearanceModeScriptSource, injectionTime: .atDocumentEnd, forMainFrameOnly: true)
self.webView.configuration.userContentController.addUserScript(appearanceModeScript)

Copy this into Xcode for easier reading, but the gist of it is to implement switchToDarkMode() by injecting CSS rules that alter the baseline defaults for the web content, and implement switchToLightMode() by removing those CSS rules. This is what my about box looks like after adopting the changes above:

This approach requires clients of RSWebContentViewController to trust that the default appearance switching will be sufficient for whatever content it wants to display. So far this simple approach has been sufficient for my needs, but I’m also in a good position to expand upon the solution should the need arise.

When Apple announced Dark Mode at WWDC 2018, one of my first thoughts was: “Aha! So that’s why Apple has us all switching our icons to template (monochrome) style images.” These images do tend to adapt pretty well to Dark Mode because the system can simply invert them and obtain a fairly usable icon, but the crude inversion doesn’t work well in all cases.

There are a lot of details to really getting Dark Mode icons perfect, and Apple talks a lot about this in the Introducing Dark Mode WWDC session. Given my limited time and resources, I took a pragmatic approach to get things looking “good enough” so I could ship a cohesive project while I hope to continue working on refinements in the future.

As with colors, asset catalogs can be a great aid in managing image variations for different appearances. Use them if you can, but bear in mind the caveats mentioned in the Adapting Colors section of this series.

Most apps will probably require some refinement of toolbar icons, the row of images typically displayed at the top of some windows. In MarsEdit, I was in pretty good shape thanks to a recent overhaul for MarsEdit 4, in which Brad Ellis revised my toolbar icons. Many, but not all, of the images have a templated style aesthetic. Here’s MarsEdit’s main window in Light Mode:

Let’s see what happens when just switch to Dark Mode without any special care for the icons:

That’s … not so good! Even my vaguely template-style icons are not being treated as templates, so they render with their literal gray colors and look pretty bad in Dark Mode. I realized I could probably do some quick Acorn work and get the template-style icons into shape, but what about the ones with splashes of color? The pencil? Should it still be yellow in Dark Mode?

I opted for a pragmatic, stop-gap solution. Without making any changes whatsoever to the graphics files, I worked some magic in code and came up with this:

That’s … actually pretty good! So what’s the magic in code I alluded to? I created a custom subclass of NSButton that will optionally set template status on the button’s image only if we’re in Dark Mode. You can see that some of the icons I’ve left untouched, because I felt their colors fit well enough in both dark and light modes. Here’s my custom RSDarkModeAdaptingToolbarButton:

class RSDarkModeAdaptingToolbarButton: NSButton {
   public var useTemplateInDarkMode: Bool = false
   var originalTemplateFlag: Bool = false

   public convenience init(image: NSImage, 
                           target: Any?, 
                           action: Selector?,
                           useTemplateInDarkMode: Bool = false) {
      self.init(image: image, target: target, action: action)
      self.useTemplateInDarkMode = useTemplateInDarkMode
   }

   override func layout() {
      // Always re-set the NSImage template state based
      // on the current dark mode setting
      if #available(macOS 10.14, *) {
         if self.useTemplateInDarkMode,
            let targetImage = self.image
         {
            var newTemplateState = self.originalTemplateFlag

            if self.effectiveAppearance.isDarkMode {
               newTemplateState = true
            }

            targetImage.isTemplate = newTemplateState
         }
      }

      super.layout()
   }
}

The key to this button’s functionality is the guarantee that layout will always be called on a button after an appearance change has occurred. This gives the button the opportunity to configure properties on itself that will affect how it is drawn. Sneaking in to set the template state on the image guarantees the NSButton superclass drawing code will treat it as a template in Dark Mode, but as a bitmap image in Light Mode.

One of the challenges I dealt with in MarsEdit was how to adapt my existing user-facing color preferences to Dark Mode:

The default values and any previously saved user customizations would be pertinent only to Light Mode. I knew I wanted to save separate values for Dark Mode, but I worried about junking up my preferences panel with separate labels and controls for each mode. After playing around with some more complicated ideas, I settled on simplicity itself: I would register and save separate values for each user-facing preference, depending on whether the app is in Dark Mode right now.

When a user switches modes, the visible color preferences in this panel change to the corresponding values for that mode. I reasoned that users are most likely to use these settings to fine-tune the appearance of the app as it appears now, and it would be intuitive to figure out if they wanted to customize the colors separately for each mode.

How did I achieve this? I decided to bottleneck access to these preferences so that as far as any consumer of the preference is concerned, there is only one value. For example, any component of my app that needs to know the “text editing color” consults a single property “bodyTextColor” on my centralized preferences controller. This is what the supporting methods, along with the property accessor, look like:

func color(forKey key: String, defaultColor: NSColor) -> NSColor {
   let defaults = UserDefaults.standard
   guard let color = defaults.rsColor(forKey: key) else {
      return defaultColor
   }
   return color
}

func setColor(color: NSColor, forKey key: String) {
   let defaults = UserDefaults.standard
   defaults.rsSetColor(color, forKey: key)
}

var bodyTextPreferenceKey: String {
   if NSApp.isDarkMode {
      return bodyTextColorForDarkModeKey
   } else {
      return bodyTextColorForLightModeKey
   }
}

@objc var bodyTextColor: NSColor {
   get {
      let key = self.bodyTextPreferenceKey
      return self.color(forKey: key, defaultColor: .textColor)
   }
   set {
      let key = self.bodyTextPreferenceKey
      self.setColor(color: newValue, forKey: key)
      self.sendNotification(.textColorPreferenceChanged)
   }
}

Because the getter and setter always consult internal properties to determine the current underlying defaults key, we always write to and read from the semantic value that the user expects. The only thing the user interface for my Preferences window needs to do is load up the color pane with the value from the getter, and respond to changes by writing with the setter.

You might be wondering what happens to the Preferences interface when the application’s appearance changes. I thought at first I would make the UI controller subscribe to appAppearanceChanged notifications, and reload the contents of the UI to match the current values of pertinent color preferences. It turned out that I didn’t even need to do that. Why?

In my centralized preferences controller, where the bottleneck methods shown above are implemented, each of the pertinent setters sends a notification that the color preference has changed. This allows observers throughout the app to update the color as needed when, for example, the user chooses a new value. If you’re using KVO or another technique for notifying clients of changes, this same approach can be adapted to that style.

After ensuring that all clients are notified when a color preference “changes,” we can reuse that same mechanism to proliferate changes in color preferences that happen to correlate with a change in appearance mode. I simply added an observer to “appAppearanceChanged” within the preference controller, where such notifications are translated into “color preference changed” notifications. The Preferences window observes these, and updates the UI. My text editors notice them, and reconfigure their appearance. Every concerned component of my app is guaranteed to know current colors regardless of how or why they have changed.

It’s worth noting that this is a scenario where using a solution like appearance-sensitive colors might also make sense. Instead of taking responsibility for notifying clients whenever these preferences change, a single color instance that adapts to current appearance would get the job done. This is a situation where even using an asset catalog doesn’t help. Because the colors in this situation are user-generated at run-time, they can’t be stored in a catalog, but a custom subclass of NSColor could achieve the same effect.

Given the dramatic visual differences between appearances, virtually every color in your app will need to be varied at drawing time to work well with the current appearance.

Use Semantic Colors

The good news is all of Apple’s built-in, semantically named colors are automatically adapted to draw with a suitable color for the current appearance. For example, if you call “NSColor.textColor.set()” in light mode, and draw a string, it will render dark text, whereas in dark mode it will render light text.

Seek out areas in your app where you use hard-coded colors and determine whether a system-provided semantic color would work just as well as, or better than, the hard-coded value. Among the most common fixes in this area will be locating examples where NSColor.white is used to clear a background before drawing text, when NSColor.textBackgroundColor will do the job better, and automatically adapt itself to Dark Mode.

Vary the Color at Drawing Time

In scenarios where a truly custom color is required, you have a few options. If the color is hard-coded in a drawing method, you may be able to get away with simply querying NSAppearance.current from the point where the drawing occurs. For example, a custom NSView subclass that simply fills itself with a hard-coded color:

override func draw(_ dirtyRect: NSRect) {
   super.draw(dirtyRect)

   // Custom yellow for light mode, custom purple for dark...

   let lightColor = NSColor(red:1, green:1, blue:0.8, alpha:1)
   let darkColor = NSColor(red:0.5, green:0.3, blue:0.6, alpha:1)

   if NSAppearance.current.isDarkMode {
      darkColor.setFill()
   } else {
      lightColor.setFill()
   }

   dirtyRect.fill()
}

Use Asset Catalogs

Special cases like above are fine when you draw your own graphics, but what about views that the system frameworks draw for you? For example, because NSBox supports drawing a custom background color, you’re unlikely to implement a custom view exactly like the one above. Its functionality is redundant with what NSBox provides “for free.” But how can you ensure that NSBox will always draw in the right color for the current appearance? It only supports one “fillColor” property.

A naive approach would involve paying attention to changes in appearance, and re-setting the fill color on NSBox every time. This would get the job done, but is more complicated and error-prone than simply setting a named system color like “textBackgroundColor” and letting it handle all the details of accommodating the current appearance.

Luckily, Apple provides a mechanism for adding custom named colors that behave the same way as standard colors do. Colors that are included in an asset catalog can be identified by name, and can be varied in the catalog to represent distinct colors depending on the appearance they are used in. In short, by defining all your hard-coded colors in asset catalogs, you can treat custom named colors like “funkyBackgroundColor” the same as standard colors like “textBackgroundColor.”

Ah, but there’s a catch. To take advantage of these fancy new asset catalog features, you need to not only build your app with Xcode 10, but you need to build it on a machine that is running macOS 10.14 or greater. Evidently the ability to generate suitable asset catalogs depends on some system functionality that Xcode 10 can’t (or at least doesn’t) replicate when running on 10.13. If you try to use these features in Xcode 10 on 10.13, you’ll run into warnings like:

warning: Named colors referencing system colors must be compiled on 10.14 to maintain dynamic behavior at runtime. Using fixed values for color 'textColor'

and

Varying images and colors by appearance requires building on macOS 10.14 or later.

Because of the utility of asset colors for both colors and images, I strongly recommend updating to Xcode 10 and building on 10.14.

Appearance-Sensitive Colors

If for some reason you can’t yet build your app with Xcode 10 on macOS 10.14, you might eke out a stopgap solution similar to mine. Because I started adopting Dark Mode shortly after WWDC 2018, before Xcode 10 or macOS 10.14 were final, I felt I needed something to simulate the behavior of catalog colors, but implemented independently of them.

I developed a class for my apps called RSAppearanceSensitiveColor, a subclass of NSColor that wraps multiple colors. If you decide to do something similar, be sure to take a look at the subclassing notes in NSColor’s documentation to ensure you override all the required methods. The most functionally important methods to override are “set”, “setFill”, and “setStroke”, because these methods are called at runtime by code that is responsible for drawing. If, for example, you implement a subclass that stores “lightModeColor” and “darkModeColor” as variants, you could add an internal helper method to resolve it:

var currentColor: NSColor {
   if NSAppearance.current.isDarkMode {
      return self.darkModeColor
   }
   else {
      return self.lightModeColor
   }
}

This takes advantage of the NSAppearance.isDarkMode property I described in Checking Appearances, making it easy to specialize based on the current appearance. Remember: that’s the one that is currently being used to perform drawing, etc. When a client that is configured with one of our colors, NSBox for example, calls our set() before drawing its background:

override public func set() {
   self.currentColor.set()
}

The actual drawing color will be appropriate for the current appearance, just as with Apple’s semantic and catalog-backed colors.

To support Dark Mode elegantly in your app, you need to not only initialize your user interface appropriately for the current appearance, but also be prepared to adapt on the fly if the user changes appearance after your interface is already visible on the screen.

In situations where you use semantic colors or consult the current appearance at drawing time, there’s nothing else to be done. Since changing the appearance invalidates all views on the screen, your app will redraw correctly without any additional intervention.

Other situations may demand more customized behavior. I’ll give a couple examples later in this series, but for now just take my word that you may run into such scenarios.

If you have a custom view that needs to perform some action when its appearance changes, the most typical way to handle this is by implementing the “viewDidChangeEffectiveAppearance” method on NSView. This is called immediately after your view’s effectiveAppearance changes, so you can examine the new appearance, and update whatever internal state you need to before subsequent drawing or event handling methods are called:

class CustomView: NSView {
   override func viewDidChangeEffectiveAppearance() {
      // Update appearance related state here...
   }
}

If you need to react to appearance changes in the context of an NSViewController, your best bet may be to use Key Value Observing (KVO) to observe changes to the “effectiveAppearance” property on the view controller’s view. This approach will set your view controller up to be notified around the same time the view itself would be.

In some situations it’s more interesting to know whether, at a high level, the application’s appearance has shifted in a significant way. For this you can observe “effectiveAppearance” on the NSApplication.shared instance. There is no standard NotificationCenter notification for this, but I found it useful enough in my code bases that I added my own.

By centralizing KVO observation of NSApp.effectiveAppearance, I can translate all such changes into NotificationCenter-based broadcasts that any component of my app can observe. To implement something like this, first declare an NSNotification.Name extension in some high-level class such as your application delegate:

extension NSNotification.Name {
   public static let appAppearanceChanged =
      NSNotification.Name("appAppearanceChanged")
}

Then implement the centralized KVO somewhere early in launch, such as in applicationDidFinishLaunching:

observer = NSApp.observe(\.effectiveAppearance) { (app, _) in
   let nc = NotificationCenter.default
   nc.post(name: .appearanceChanged, object: app)
}

Now any code in your app that needs to be alerted when the app changes appearance can observe NSNotification.Name.appAppearanceChanged and respond by adjusting whatever it needs to.

As you adapt your app to support Dark Mode, you may run into situations where you need to determine, in code, what the active appearance is. This is most typical in custom views that vary their drawing based on the current appearance, but you may also need to test higher level appearance traits to determine, for example, whether the whole application is being run “in Dark Mode” or not.

Current and Effective Appearances

To work effectively with Dark Mode support, you must appreciate the distinction between a few key properties that are all of type NSAppearance. Take some time to read the documentation and watch the videos I referenced in Educational Resources, so you really understand them. Here is a capsule summary to use as reference in the context of these articles:

• appearance is a property of objects, such as NSApplication, NSWindow, and NSView, that implement the NSAppearanceCustomization protocol. Any such object can have an explicit appearance deliberately set on it, affecting the appearance of both itself and any objects that inherit appearance from it. As a rule, views inherit the appearance of their window, and windows inherit the appearance of the app.
• effectiveAppearance is a property of those same objects, taking into account the inheritance hierarchy and returning a suitable appearance in the likely event that no explicit value has been set on the object.
• NSAppearance.current or +[NSAppearance currentAppearance] is a class property of NSAppearance that describes the appearance that is currently in effect for the running thread. Practically speaking you can think of this property as an ephemeral drawing variable akin to the current fill color or stroke color. Its value impacts the manner in which drawing that is happening right now should be handled. Don’t confuse it with high-level user-facing options about which mode is set for the application as a whole.

High-Level Appearance Traits

As you modify your code to respect the current or effective appearance, you will probably need to make high level assessments like “is this appearance light or dark?” Because of the aforementioned complication that there are many types of NSAppearance, that they can be nested, etc., it’s not possible to simply compare the current appearance with a named appearance. Instead, you use a method on NSAppearance designed to evaluate which high-level appearance it is most like. If it’s a matter of simply distinguishing between light and dark appearances, you can use something like this:

let mode = NSAppearance.current
let isDark = mode.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua

In my applications, I found myself testing NSAppearance instances for lightness or darkness commonly enough that I implemented an “isDarkMode” property in an extension to NSAppearance:

// NSAppearance extension

@objc(rsIsDarkMode)
public var isDarkMode: Bool {
   let isDarkMode: Bool

   if #available(macOS 10.14, *) {
      if self.bestMatch(from: [.darkAqua, .aqua]) == .darkAqua {
         isDarkMode = true
      } else {
         isDarkMode = false
      }
    } else {
        isDarkMode = false
    }

    return isDarkMode
}

As you can see this is laden with the requisite tests to ensure it works even if the app is running on a pre-10.14 Mac. A nice side-effect of centralizing this code in one place, is eliminating the need to include those checks at every call point.

This helper method is handy for working with NSAppearance instances, but in some contexts what I really want to know is bluntly: is this app running in dark mode or not? To accommodate this, I extend NSApplication to offer an identically named property:

// NSApplication extension

@objc(rsIsDarkMode)
public var isDarkMode: Bool {
   if #available(macOS 10.14, *) {
      return self.effectiveAppearance.isDarkMode
   } else {
      return false
   }
}

This method takes advantage of NSAppearance.isDarkMode, so it doesn’t have to replicate any of the important, but slightly clumsy “bestMatch” code either.

Having these convenient methods at my fingertips has been a great aid because it allows me to quickly answer the high-level question of whether an appearance is dark or not, regardless of whether I’m implementing drawing code or making a higher-level semantic interpretation of the application’s user-facing appearance.

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:

1. The system considers the app to be compatible with Dark Mode
2. 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:

func applicationDidFinishLaunching(_ notification: Notification) {
   #if DEBUG_DARK_AQUA
      NSApp.appearance = NSAppearance(named: .darkAqua)
   #endif
}

This arrangement will allow you to run Xcode and other apps in Light Aqua while debugging your own app in Dark Mode.

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:

WWDC Sessions

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.

Documentation

Apart from the reference documentation on NSAppearance, be sure to read the longer-form Supporting Dark Mode in Your Interface, and Providing Images for Different Appearances. These high-level guides will orient you to the types of work you will likely need to do in your app. Finally, the macOS 10.14 Release Notes include a number of details about Dark Mode, and particularly about special background blending modes and how they affect the user interface of an application.

Immerse Yourself

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.