DEV Community: Thomas Steiner

Web Apps on macOS Sonoma 14 Beta

Thomas Steiner — Wed, 07 Jun 2023 13:39:59 +0000

Executive summary 🔗

With macOS Sonoma, Apple goes all-in on the concept of installable web apps. They're highly integrated in the overall macOS experience and don't give away their web roots by not showing any Safari UI at all.

Testing environment 🔗

Tested on macOS Sonoma 14.0 Beta (23A5257q) with Safari version 17.0 (19616.1.14.11.11). It probably doesn't matter, but the testing device was a 13-inch, M1, 2020 MacBook Pro.

Install experience 🔗

On macOS Sonoma, you can add a website—any website, not just apps with a manifest—to your Dock. Go to the Share icon and click Add to Dock , or use the menu item File > Add to Dock.

Adding an app via the Share icon.

Adding an app via the File menu.

You can adjust the name and icon if desired. The URL is the URL you're on for pages without a manifest, or the start_url for pages with a manifest. It can't be changed. For pages without an icon, Safari will create a fallback icon based on the first letter of the page's title.

👀 Observation: Unlike on iOS/iPadOS, you can't add the same app twice, unless you rename it.

App name and icon are adjustable, the URL is not.

The web app icon then appears in your Dock. Maskable icons are supported, and the typical macOS squircle shape is respected. Closing all windows of an app leaves the app running, aligned with macOS UX paradigms.

👀 Observation: Unlike on Chrome, the app doesn't launch immediately and "morph" from in-tab to in-app, but instead you remain on the tab and need to launch the app manually.

Web app added to the Dock.

When right-clicking the Dock icon, you can uncheck Keep in Dock and still launch the app via Launchpad, Spotlight Search, or even just by double-clicking the app icon in ~/Applications/.

Launch experience 🔗

The out-of-the box launch experience of web apps is fantastic. Nowhere does it give away that this is a web app. For apps with a manifest, there's no Safari UI whatsoever, and the expectation is that such apps are single-page apps that provide their own navigation controls. If an app is well made, lay persons probably wouldn't be able to tell that something is a web app.

Web app running without any Safari UI.

👀 Observation: Different from iOS/iPadOS, credentials in cookies are copied over, so if you were logged in when running in the tab, you're logged in when you launch the app. No other storage means apart from cookies are copied. "When a user adds a website to their Dock, Safari will copy the website's cookies to the web app. That way, if someone is logged into their account in Safari, they will remain logged in within the web app. This will only work if the authentication state is stored within cookies. Safari does not copy over any other kind of local storage. After a user adds a web app to the Dock, no other website data is shared, which is great for privacy".

👀 Observation: Web Inspector (DevTools) is blocked, even with the Show features for web developers checkbox checked. There's no Develop menu item nor can you right-click and Inspect Element. This looks like a conscious decision.

👀 Observation: Extensions don't run and likewise aren't displayed. Also probably a conscious decision.

👀 Observation: Same-origin links are handled in-app, cross-origin links open in the default browser.

If a user navigates to an already installed app in Safari, a prompt is displayed that invites the user to Open in web app.

Prompt inviting the user to Open in web app.

macOS integration experience 🔗

Web apps on Mac let you focus on the websites you use all the time, separate from the rest of your browsing. Like all Mac apps, web apps work great with Stage Manager, Mission Control, and keyboard shortcuts like Command + Tab. Web apps can be opened from the Dock, Launchpad, and Spotlight Search.

Multitasking experience.

Spotlight search experience.

Launchpad experience.

Stage Manager experience.

All web apps have an About dialog.

Settings and permissions 🔗

Web apps work with AutoFill credentials from iCloud Keychain and from third-party apps that have adopted theCredential Provider Extension API. Users can grant permission to a web app to use their camera, microphone and location in the same way they grant such permissions to other Mac apps through system prompts and the Privacy & Security section of System Settings.

System settings with Camera permissions.

Web apps on Mac supportweb push,badging, and all the usual web standards implemented by WebKit, just like web appson iOS and iPadOS.

👀 Observation: There seems to be a bug where the hosting Web App appears as the app requesting the Notifications permission. Notifications then work as expected, though, including using the correct icon.

Notifications permission prompt with the wrong app name and icon.

Web apps have their own Settings dialog. In General , the app name and icon can be changed and navigation controls can be toggled on or off. Thetheming behavior of the title barcan be changed, too.

👀 Observation: Navigation controls are toggled off when there's a manifest with "display": "standalone". In all other cases, even if a manifest exists but with a different "display" mode,

Web app Settings dialog on the General tab.

👀 Observation: There's currently a bug where web apps don't correctly report matchMedia('(display-mode: standalone)'). Added to the Dock web apps think they run in a tab.

With navigation controls enabled, there's an Open in Safari icon in the upper right corner. Despite its label, it actually respects the user's default browser.

_ Open in Safari icon._

Web pages get navigation affordances in the form of a back and forward button. There's no reload button.

Back and forward buttons.

👀 Observation: With navigation controls toggled to off, the title of the web app sourced from the manifest is not shown. With navigation controls toggled to on, the title sourced from the <title> is shown.

👀 Observation: When you right-click, there's a context menu with Reload or Back and Reload. This works independent from whether navigation controls are toggled on or off.

The Privacy tab allows the user to clear website data and links into the Privacy & Security Settings of the System Settings app.

Web app Settings dialog on the Privacy tab.

Technical analysis 🔗

All apps are stored in ~/Applications/. The package contents of each apps are:

a _CodeSignature folder with code signature metadata
a Resources folder with just the app icons as a singleApplicationIcon.icns file
an Info.plist file.

The package contents of an app.

The Info.plist file interestingly contains an XML version of key parts of the manifest and metadata about the app.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleIconFile</key>
    <string>ApplicationIcon</string>
    <key>CFBundleIdentifier</key>
    <string
      >com.apple.Safari.WebApp.svgco.de.53298B34-AF7F-4074-9CA9-1EE46B7E3E83</string
    >
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>SVGcode</string>
    <key>CFBundlePackageType</key>
    <string>AAPL</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFBundleSupportedPlatforms</key>
    <array>
      <string>MacOSX</string>
    </array>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>x-webkit-app-launch</string>
        </array>
        <key>LSHandlerRank</key>
        <string>None</string>
      </dict>
    </array>
    <key>CFBundleVersion</key>
    <string>1</string>
    <key>LSMinimumSystemVersion</key>
    <string>14.0</string>
    <key>LSTemplateApplication</key>
    <true />
    <key>LSTemplateApplicationParameters</key>
    <dict>
      <key>CFBundleIdentifier</key>
      <string>com.apple.Safari.WebApp</string>
      <key>TemplateAppUUID</key>
      <string>53298B34-AF7F-4074-9CA9-1EE46B7E3E83</string>
      <key>defaultarguments</key>
      <true />
      <key>teamIdentifier</key>
      <string></string>
    </dict>
    <key>Manifest</key>
    <dict>
      <key>description</key>
      <string
        >SVGcode is a Progressive Web App that lets you convert raster images
        like JPG, PNG, GIF, WebP, AVIF, etc. to vector graphics in SVG
        format.</string
      >
      <key>display</key>
      <string>standalone</string>
      <key>icons</key>
      <array>
        <dict>
          <key>purpose</key>
          <string>maskable</string>
          <key>sizes</key>
          <string>1024x1024</string>
          <key>src</key>
          <string>https://svgco.de/favicon.png</string>
          <key>type</key>
          <string>image/png</string>
        </dict>
        <dict>
          <key>purpose</key>
          <string>any</string>
          <key>sizes</key>
          <string>150x150</string>
          <key>src</key>
          <string>https://svgco.de/favicon.svg</string>
          <key>type</key>
          <string>image/svg+xml</string>
        </dict>
        <dict>
          <key>purpose</key>
          <string>monochrome</string>
          <key>sizes</key>
          <string>150x150</string>
          <key>src</key>
          <string>https://svgco.de/favicon-bw.svg</string>
          <key>type</key>
          <string>image/svg+xml</string>
        </dict>
      </array>
      <key>name</key>
      <string>SVGcode</string>
      <key>scope</key>
      <string>https://svgco.de</string>
      <key>short_name</key>
      <string>SVGcode</string>
      <key>start_url</key>
      <string>https://svgco.de/</string>
      <key>theme_color</key>
      <string>#ffffff</string>
    </dict>
    <key>WKPushBundleMetadata</key>
    <dict>
      <key>manifestId</key>
      <string>https://svgco.de/</string>
    </dict>
  </dict>
</plist>

Similar to iOS/iPadOS, web apps run in the context of a separate process calledWeb App.app, which resides in/System/Volumes/Preboot/Cryptexes/App/System/Library/CoreServices/Web App.app.

👀 Observation: Separating Safari and Web App allows both to run independently. You can open a Web app without opening Safari, you can close Safari without all web apps closing.

The Web App.app app in Finder.

Each web app runs as its own process of kind Web, accompanied by a number of helper processes of kind Apple. They can all be seen in Activity Monitor.

Activity Monitor showing all processes associated with a web app.

Wish list for Apple 🔗

(Also see Most wanted PWA features on iOS/iPadOS/macOS Safari.)

Add support for theFile System Access API, so users can install apps and edit files directly, rather than opening them and then downloading a copy. [🧭 231706]
Add support forDataTransferItem.getAsFileSystemHandle(), so users can drag and drop files into web apps and edit the file. [🧭 257792]
Add support for theWeb Share Target API, so you can share data to installed web apps. [🧭 194593]
Let web apps programmatically trigger the Add to Dock flow, since the Share icon and the File menu install ways are hard to discover. [🧭 255716]
Add support for theWindow Controls Overlay API, so the gorgeous current experience can be made even more gorgeous. [🧭 257782]

Spotify native app title bar experience.

Spotify web app title bar experience.

Add support for theFile Handling API, so web apps can open files from Finder by double click if the web app is registered as the default file handler for a given file type, or by right click and then Open with if the web app can handle a file type, but isn't the default file handler. [🧭 257783]
Add support for theLaunch Handler API, so web apps can decide how they want to handle launch events. [🧭 257785]
Reflect the cookie-copying logic on iOS/iPadOS. It's a very frustrating experience if you have to log in twice, even more so if two-factor authentication is involved. [🧭 257786]
Allow users to turn off the Open in web app prompt.

Recommendations for Chrome 🔗

Better respect macOS' design paradigms. Currently web app icon handling looks not integrated and icon shapes are all over the place. The examples below are all web apps installed via Chrome.

Web app icon shapes installed from Chrome don't respect the squircle.

Move the extension puzzle piece and the Window Controls Overlay chevron into the three dots menu. Web apps can look so much cleaner without both in plain sight.

Window Controls Overlay chevron and extension puzzle piece clutter the UI of Chrome-installed apps.

New Fugu API needs 🔗

With Chrome and Safari now allowing web apps to be installed on macOS, it would be fantastic if installed apps could respect macOS UX guidelines and populate the system-level menu. Ideally Apple and Google engage jointly on the corresponding Project Fugu 🐡 API request tracked incrbug/1295253.

Web app default menu.

Conclusion 🔗

Web apps in macOS Sonoma 14 Beta seamlessly integrate into the macOS experience, with no or very little visible Safari UI and with support for various operating system features. There is an enormous potential for web apps on macOS to succeed, and if Apple only works on a third of the items on my wish list, the potential is even bigger.

Project Fugu 🐡 at W3C TPAC

Thomas Steiner — Sat, 21 Sep 2019 16:03:15 +0000

This week, I attended my now third W3CTPAC. After TPAC 2017 in Burlingame, CA, United States of America and TPAC 2018 in Lyon, France, TPAC 2019 was held in Fukuoka, Japan. For the first time, I felt like I could somewhat meaningfully contribute and had at least a baseline understanding of the underlying W3C mechanics. As each year, the TPAC agenda was crammed and overlaps were unavoidable. Below is the write-up of the meetings I had time to attend.

Day 1

On Monday, I attended the Service Workers Working Group (WG) meeting. The agenda this time was a mix of implementor updates, new proposals, and a lot of discussion of special cases. I know Jake Archibald is working on a summary post, so I leave it to him to summarize the day. Theraw meeting minutes are available in case you're interested.

Day 2

On Tuesday, I visited theWeb Application Security Working Group meeting as an observer. I was mostly interested in this WG because theagenda promised interesting proposals like Apple's/.well-known/change-passwordthat was met with universal agreement. Some interesting discussion also sparked around again Apple'sisLoggedIn() API proposal. I was reminded of why on the web we can't have nice things through an attack vector that leverages HSTS for tracking purposes. Luckily there isbrowser mitigation in place to prevent this.Themeeting minutes cover the entire day.

Day 3

Wednesday was unconference day with59(!) breakout sessions. Other than the at times tedious working group sessions,I find breakout sessions to be oftentimes more interesting and an opportunity to learn new things.

Breakout Session JS Built-in Modules

The first breakout session I attended was onJS built-in modules, a TC39 proposal by Apple for aJavaScript Built-in Library. The session's minutes are available, in general there was a lot of discussion and disagreement around namespaces and how built-in modules should be governed.

Breakout Session New Module Types: JSON, CSS, and HTML

The next session was onnew module types for JSON, CSS, and HTML. As the developer of<dark-mode-toggle>, I'm fully in favor of getting rid of the clumsyinnerHTML all the things!!!1! approach that vanilla JS custom elements currently make the programmer to follow. If you're likewise interested, subscribe to theCSS Modules issue and the HTML Modules issue in the Web Components WG repo. The discussion circulated mostly around details how @imports would work and how to convey the type of the import to avoid security issues, for example following the <link rel="preload"> way. The meeting minutes have the full details.

// Non-working example
import styles from 'styles.css' as stylesheet;
import settings from 'settings.json' as json;

Breakout Session Mini App Standardization

The Mini App Standardization session, organized by the Chinese Web Interest Group, was super interesting to me.In preparation of theGoogle Developer Days in Shanghai, China, that I spoke at right before TPAC, I havelooked at WeChat mini programs and documented the developer experience and how close to and yet how far from the web they are. A couple of days before TPAC, the Chinese Web Interest Group had released awhite paper that documents their ideas. The success the various mini apps platforms have achieved deserves our full respect. There were, however, various voices—including from theTAG—that urged the various stakeholders to converge their work with efforts made in the area ofProgressive Web Apps, for example around the Web App Manifest rather than create yet another manifest-like format. Read the full session minutes for all details. One of the results of the session was the creation of theMiniApps Ecosystem Community Group that I hope to join.

Breakout Session For a More Capable Web—Project Fugu

Together with Anssi Kostiainen from Intel andJohn Jansen from Microsoft,I organized a breakout session for a more capable web under the umbrella of Project Fugu 🐡. You can see our slides embedded below. In the session we argue that to remain relevant with native, hybrid, or mini apps, web apps, too,need access to a comparable set of APIs. We briefly touched upon the APIs being worked on by the cross-company project partners,and then opened the floor for an open discussion on why we see the browser-accessible web in dangerif we don't move it forward now,despite all fully acknowledged challenges around privacy, security, and compatibility. You can follow the discussion in the excellent(!) session minutes, courtesy of Anssi.

Day 4 and Day 5

Thursday and Friday were dedicated to the Devices and Sensor WG. The agenda was not too packed, but still kept us busy for one and a half days. We discussed almost from the start about permissions and how they should be handled. Permissions are a big topic in Project Fugu 🐡 and I'm happy that there's work ongoing in the TAG to improve the situation, including efforts around the Permissions API that is unfortunately not universally supported, leading to inconsistencies with some APIs having a static method for getting permission, others asking for permission upon the first usage attempt, and yet others to integrate with the Permissions API.For the Geolocation Sensor API, we agreed to try retrofitting expressive configuration of foreground tracking into the Geolocation API specification instead of doing it in Geolocation Sensor, which should improve vendor adoption. For geofencing and background geolocation tracking, we decided to explore Notification Triggers and Wake Locks respectively, which both weren't options when the work on Geolocation Sensor was started initially.

Maryam Mehrnezhad, an invited expert in the working group whose research is focused on privacy and security, presented on and discussed with us the implications on both fields that sensors potentially have and whether mitigation like accuracy bucketing or frequency capping are effective. The minutes capture the conversation well.

Finally, we changed the surface of the Wake Lock API hopefully for the last time. The previous changes just didn't feel right from a developer experience point of view, so better change the API while it's behind a flag than be sorry forever. I reckon I do feel sorry for the implementors Rijubrata Bhaumik and Raphael Kubo da Costa… 🙇

partial interface Navigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

partial interface WorkerNavigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

[Exposed=(Window,DedicatedWorker)]
interface WakeLock {
  Promise<unsigned long long> request(WakeLockType type);
  Promise<void> release(unsigned long long wakeLockID);
};

dictionary WakeLockEventInit {
  required unsigned long long wakeLockID;
};

[Exposed=(Window,DedicatedWorker)]
interface WakeLockEvent : Event {
  constructor(DOMString type, WakeLockEventInit init);
  readonly attribute unsigned long long wakeLockID;
};

As a general theme, we "hardened" a number of APIs, for example decided to integrate geolocation with Feature Policy and now require a secure connection for the Battery Status API. The chairs Anssi and Reilly Grant have scribed the one and a half days brilliantly, the minutes for day 1 and day 2 are both online.

Conclusion

As I wrote in the beginning, TPAC slowly starts to feel like a venue where I can make some valuable contributions. Rowan Merewood put it like this in a tweet:

The biggest thing I'm learning at [#W3Ctpac] is if you want to change the web, it's a surprisingly small group of people you need to convince. The surrounding appearance of the W3C and all its language is intimidating, but underneath it's just other human beings you can talk to.

To which Mariko Kosaka fittingly responds:

[Y]]eah, but let's not forget getting to talk to that small set of people most often comes with being very, very, very privileged. […]

It's indeed a massive privilege to work for a company that has the money to take part in W3C activities, fly people across the world, and let them stay in five star conference hotels. With all the love for the web and all the great memories of a fantastic TPAC, let's not forget: the web is threatened from multiple angles, and being able to work in the standards bodies on defending it is a privilege of the few. Both shouldn't be the case.

Not All Is Nothing—Finding Out If the Browser Supports a Given Media Query

Thomas Steiner — Mon, 16 Sep 2019 00:19:54 +0000

On the Google Chrome team, we're working on solving the interesting problem that some platforms like Windows 10 show a native ← Back button in the app window's title bar when the user has navigated into a standalone or fullscreen Progressive Web App (PWA). This can lead to PWAs inadvertently showing two means of in-app navigation: one from the operating system and one from the app itself. The screenshot below from Twitter's PWA illustrates this issue well. The two back buttons are highlighted in red, the Windows-generated button is in the title bar.

In order for PWAs to be able to detect the presence or absence of system-level navigation controls, we've proposed a new, aptly named CSS media query called navigation-controls. The Explainer goes into great detail on how this media query works, but the most basic way to use it can be seen in the code sample below.

/**
 * Hide the app's own back button if the browser or the OS
 * provides any navigation controls.
 */
@media (navigation-controls) {
  #back-button {
    display: none;
  }
}

This leads to the interesting question how developers can find out via JavaScript if a media query is supported and understood at all by a browser. Note that the @supports CSS at-rule can't be used to detect media query support. Before we dive into this question, let's get some things defined first.

Media types

Media types describe the general category of a device. Some examples are print, screen, speech, or simply the default media type all.

Media features

Media features describe specific characteristics of the user agent, output device, or environment. Media feature expressions test for their presence or value. Examples are prefers-color-scheme, hover, and many more. Media feature expressions must always be surrounded by parentheses.

Let's take a media feature expression like (max-width: 600px). From a JavaScript context, you can test if it matches as shown below.

window.matchMedia('(max-width: 600px)').matches;
// Returns either `true` or `false`.

Some media features are evaluated in theboolean context. This means that if the feature would be true for any value other than the number 0, a <dimension> with the value 0, the keyword none, or a value explicitly defined by that media feature to evaluate as false in a boolean context, the media feature evaluates to true. This is oftentimes a convenient shorthand for features like hoverthat accepts the two values none and hover. Usually you don't mind for the none value, but instead want to make sure you only use hover events if the user agent has some kind of hoverable device like a mouse. In this case, you can simply test for @media (hover) { … }.

Testing if a browser understands a media query

The window.matchMedia() method returns a MediaQueryList whose media read-only property is a DOMString representing a serialized media query. What this means in practice is that we can use this to normalize media query expression strings.

// Note the superfluous spaces and the '+' before the width
window.matchMedia('( max-width: +600px)').media;
// Returns `"(max-width: 600px)"`.

The newly proposed media feature navigation-controls—apart from back—hasnone as one of its allowed keywords, and is evaluated in a boolean context. Bringing things together, we can thus check if the browser understands it by looking at the media property.

window.matchMedia('(navigation-controls)').media;
// Returns `"not all"` when the browser doesn't understand
// the media query, or `"(navigation-controls)"` else.

The interesting value here is "not all", meaning the browser doesn't understand the media feature. If the browser doesn't have the slightest clue what navigation-controls is about, it tells you the serialization of this (unknown) media feature is something that will never match: the media type @media not all. Because not all is nothing.

A quick look at WeChat's Mini Programs

Thomas Steiner — Thu, 15 Aug 2019 10:16:05 +0000

While preparing for my presentation at the Google Developer Days 2019 in Shanghai, China I was reminded again that China is a market where few super apps like WeChat host a gazillion mini apps or mini programs that fulfill everyday needs like booking cabs, reserving tables, etc.

I got curious and downloaded the SDK and after playing a bit with the Your First Mini App tutorial, I realized the whole thing is so close to building for the actual web, it both fascinates, intrigues, and honestly somewhat infuriates me.

App Architecture

You style your apps with WXSS, which is essentially CSS with some neat additions like responsive pixels.

page-section-gap{
  box-sizing: border-box;
  padding: 0 30rpx;
}

.page-body-button {
  margin-bottom: 30rpx;
}

You write your app logic with JavaScript (or TypeScript), with App as the top level object and wx as the object you get all the cool capabilities from. The API is incredibly powerful. Here are the keys of the wx object:

[
  "addCard",
  "addNativeDownloadTask",
  "addPhoneContact",
  "addWeRunData",
  "arrayBufferToBase64",
  "authorize",
  "base64ToArrayBuffer",
  "batchGetContactDirectly",
  "bindPaymentCard",
  "calRqt",
  "canIUse",
  "cancelDownloadAppTask",
  "canvasGetImageData",
  "canvasPutImageData",
  "canvasToTempFilePath",
  "captureScreen",
  "checkIsSoterEnrolledInDevice",
  "checkIsSupportFacialRecognition",
  "checkIsSupportSoterAuthentication",
  "checkSession",
  "chooseAddress",
  "chooseContact",
  "chooseImage",
  "chooseInvoice",
  "chooseInvoiceTitle",
  "chooseLocation",
  "chooseMedia",
  "chooseMessageFile",
  "chooseMultiMedia",
  "chooseShareGroup",
  "chooseVideo",
  "chooseWeChatContact",
  "clearStorage",
  "clearStorageSync",
  "closeBLEConnection",
  "closeBluetoothAdapter",
  "closeSocket",
  "cloud",
  "compressImage",
  "connectSocket",
  "connectWifi",
  "createAnimation",
  "createAudioContext",
  "createBLEConnection",
  "createCameraContext",
  "createCanvasContext",
  "createContext",
  "createInnerAudioContext",
  "createIntersectionObserver",
  "createInterstitialAd",
  "createLivePlayerContext",
  "createLivePusherContext",
  "createMapContext",
  "createOffscreenCanvas",
  "createRewardedVideoAd",
  "createSelectorQuery",
  "createUDPSocket",
  "createVideoContext",
  "createWorker",
  "downloadApp",
  "downloadAppForIOS",
  "downloadFile",
  "downloadSilkVoice",
  "drawCanvas",
  "enterContact",
  "env",
  "error",
  "exitVoIPChat",
  "faceVerifyForPay",
  "getABTestConfig",
  "getAccountInfoSync",
  "getAppInstallState",
  "getAvailableAudioSources",
  "getBLEDeviceCharacteristics",
  "getBLEDeviceServices",
  "getBackgroundAudioManager",
  "getBackgroundAudioPlayerState",
  "getBackgroundFetchData",
  "getBackgroundFetchToken",
  "getBatteryInfo",
  "getBatteryInfoSync",
  "getBeacons",
  "getBluetoothAdapterState",
  "getBluetoothDevices",
  "getClipboardData",
  "getConnectedBluetoothDevices",
  "getConnectedWifi",
  "getCookies",
  "getExtConfig",
  "getExtConfigSync",
  "getFileInfo",
  "getFileSystemManager",
  "getHCEState",
  "getImageInfo",
  "getLabInfo",
  "getLaunchOptionsSync",
  "getLocation",
  "getLogManager",
  "getMenuButtonBoundingClientRect",
  "getNetworkType",
  "getOpenDeviceId",
  "getPublicLibVersion",
  "getRealtimeLogManager",
  "getRecorderManager",
  "getResPath",
  "getSavedFileInfo",
  "getSavedFileList",
  "getScreenBrightness",
  "getSelectedTextRange",
  "getSetting",
  "getShareInfo",
  "getStorage",
  "getStorageInfo",
  "getStorageInfoSync",
  "getStorageSync",
  "getSystemInfo",
  "getSystemInfoSync",
  "getUpdateManager",
  "getUserInfo",
  "getWeRunData",
  "getWifiList",
  "getWxSecData",
  "hideKeyboard",
  "hideLoading",
  "hideNavigationBarLoading",
  "hideShareMenu",
  "hideTabBar",
  "hideTabBarRedDot",
  "hideToast",
  "installDownloadApp",
  "isSDKError",
  "isSystemError",
  "isThirdError",
  "joinVoIPChat",
  "launchApplicationDirectly",
  "launchApplicationForNative",
  "launchMiniProgram",
  "loadFontFace",
  "loadPaySpeechDialectConfig",
  "login",
  "makePhoneCall",
  "makeVoIPCall",
  "navigateBack",
  "navigateBackApplication",
  "navigateBackH5",
  "navigateBackMiniProgram",
  "navigateBackNative",
  "navigateTo",
  "navigateToDevMiniProgram",
  "navigateToMiniProgram",
  "navigateToMiniProgramDirectly",
  "nextTick",
  "notifyBLECharacteristicValueChange",
  "notifyBLECharacteristicValueChanged",
  "offAppHide",
  "offAppShow",
  "offAudioInterruptionBegin",
  "offAudioInterruptionEnd",
  "offError",
  "offLocalServiceDiscoveryStop",
  "offLocalServiceFound",
  "offLocalServiceLost",
  "offLocalServiceResolveFail",
  "offPageNotFound",
  "offWindowResize",
  "onAccelerometerChange",
  "onAppEnterBackground",
  "onAppEnterForeground",
  "onAppHide",
  "onAppRoute",
  "onAppRouteDone",
  "onAppShow",
  "onAppUnhang",
  "onAudioInterruptionBegin",
  "onAudioInterruptionEnd",
  "onBLECharacteristicValueChange",
  "onBLEConnectionStateChange",
  "onBLEConnectionStateChanged",
  "onBackgroundAudioPause",
  "onBackgroundAudioPlay",
  "onBackgroundAudioStop",
  "onBackgroundFetchData",
  "onBeaconServiceChange",
  "onBeaconUpdate",
  "onBluetoothAdapterStateChange",
  "onBluetoothDeviceFound",
  "onCompassChange",
  "onDeviceMotionChange",
  "onDownloadAppStateChange",
  "onError",
  "onEvaluateWifi",
  "onGetWifiList",
  "onGyroscopeChange",
  "onHCEMessage",
  "onKeyboardHeightChange",
  "onLocalServiceDiscoveryStop",
  "onLocalServiceFound",
  "onLocalServiceLost",
  "onLocalServiceResolveFail",
  "onLocationChange",
  "onMemoryWarning",
  "onNativeEvent",
  "onNetworkStatusChange",
  "onPageNotFound",
  "onPageReload",
  "onSocketClose",
  "onSocketError",
  "onSocketMessage",
  "onSocketOpen",
  "onTapNavigationBarRightButton",
  "onUploadEncryptedFileToCDNProgress",
  "onUserCaptureScreen",
  "onVoIPChatInterrupted",
  "onVoIPChatMembersChanged",
  "onVoIPChatSpeakersChanged",
  "onVoicePlayEnd",
  "onWebviewEvent",
  "onWifiConnected",
  "onWindowResize",
  "openBluetoothAdapter",
  "openBusinessView",
  "openCard",
  "openDeliveryList",
  "openDocument",
  "openGoldenRedPacketDetail",
  "openLocation",
  "openMiniProgramHistoryList",
  "openMiniProgramProfile",
  "openMiniProgramSearch",
  "openMiniProgramStarList",
  "openOfficialAccountProfile",
  "openOfflinePayView",
  "openQRCode",
  "openSetting",
  "openUrl",
  "openUserProfile",
  "openWCPayCardList",
  "operateWXData",
  "pageScrollTo",
  "pauseBackgroundAudio",
  "pauseDownloadAppTask",
  "pauseVoice",
  "playBackgroundAudio",
  "playVoice",
  "presetWifiList",
  "preventApplePayUI",
  "previewImage",
  "queryDownloadAppTask",
  "reLaunch",
  "readBLECharacteristicValue",
  "redirectTo",
  "removeSavedFile",
  "removeStorage",
  "removeStorageSync",
  "removeTabBarBadge",
  "removeUserCloudStorage",
  "reportAction",
  "reportAnalytics",
  "reportIDKey",
  "reportKeyValue",
  "reportMonitor",
  "request",
  "requestMallPayment",
  "requestPayment",
  "requestPaymentToBank",
  "requestVirtualPayment",
  "resumeDownloadAppTask",
  "saveFile",
  "saveImageToPhotosAlbum",
  "saveVideoToPhotosAlbum",
  "scanCode",
  "secureTunnel",
  "seekBackgroundAudio",
  "sendBizRedPacket",
  "sendGoldenRedPacket",
  "sendHCEMessage",
  "sendSocketMessage",
  "setBackgroundColor",
  "setBackgroundFetchToken",
  "setBackgroundTextStyle",
  "setClipboardData",
  "setCookies",
  "setCurrentPaySpeech",
  "setEnableDebug",
  "setInnerAudioOption",
  "setKeepScreenOn",
  "setLabInfo",
  "setNavigationBarAlpha",
  "setNavigationBarColor",
  "setNavigationBarRightButton",
  "setNavigationBarTitle",
  "setPageStyle",
  "setResPath",
  "setScreenBrightness",
  "setStorage",
  "setStorageSync",
  "setTabBarBadge",
  "setTabBarItem",
  "setTabBarStyle",
  "setTopBarText",
  "setUserCloudStorage",
  "setWifiList",
  "shareAppMessageForFakeNative",
  "showActionSheet",
  "showLoading",
  "showModal",
  "showNavigationBarLoading",
  "showShareActionSheet",
  "showShareMenu",
  "showTabBar",
  "showTabBarRedDot",
  "showToast",
  "startAccelerometer",
  "startBeaconDiscovery",
  "startBluetoothDevicesDiscovery",
  "startCompass",
  "startCustomFacialRecognitionVerify",
  "startCustomFacialRecognitionVerifyAndUploadVideo",
  "startDeviceMotionListening",
  "startFacialRecognitionVerify",
  "startFacialRecognitionVerifyAndUploadVideo",
  "startGyroscope",
  "startHCE",
  "startLocalServiceDiscovery",
  "startLocationUpdate",
  "startLocationUpdateBackground",
  "startPullDownRefresh",
  "startRecord",
  "startSoterAuthentication",
  "startWifi",
  "stopAccelerometer",
  "stopBackgroundAudio",
  "stopBeaconDiscovery",
  "stopBluetoothDevicesDiscovery",
  "stopCompass",
  "stopDeviceMotionListening",
  "stopGyroscope",
  "stopHCE",
  "stopLocalServiceDiscovery",
  "stopLocationUpdate",
  "stopPullDownRefresh",
  "stopRecord",
  "stopVoice",
  "stopWifi",
  "switchTab",
  "traceEvent",
  "triggerGettingWidgetData",
  "updatePerfData",
  "updateShareMenu",
  "updateVoIPChatMuteConfig",
  "uploadEncryptedFileToCDN",
  "uploadFile",
  "uploadSilkVoice",
  "uploadWeRunData",
  "verifyPaymentPassword",
  "version",
  "vibrateLong",
  "vibrateShort",
  "voiceSplitJoint",
  "writeBLECharacteristicValue"
]

You describe your interface with WXML, which is something between JSX, Vue's declarative rendering; it also reminds me of old concepts like XSLT's <xsl:if>:

<view wx:if="{{view == 'WEBVIEW'}}"> WEBVIEW </view>
<view wx:elif="{{view == 'APP'}}"> APP </view>
<view wx:else="{{view == 'MINA'}}"> MINA </view>

Overall a really nice separation of concerns. I could very well imagine being productive with this in no time. The onboarding experience of the documentation is pretty neat. The SDK is well made with (essentially an adapted) Chrome DevTools integrated and some VS Code like features like code completion.

Programming Concept

The overall programming concept reminds of OpenSocial (if anyone remembers that) where there is a baseline assumption of a logged in user whose social graph can be explored:

// OpenSocial
osapi.people.getViewer().execute(function(result) {
  if (!result.error) {
    console.log('Your name is ' + result.displayName + '!');
  }
});

// WeChat
wx.getSetting({
  success: res => {
    if (res.authSetting['scope.userInfo']) {
      wx.getUserInfo({
        success: res => {        
          console.log(res.userInfo);
        }
      });
    }
  }
});

Component Library

They also have nice set of declarative components, think web components essentially, that you can create with WXML and interact with from JavaScript:

<map
  id="myMap"
  style="width: 100%; height: 300px;"
  latitude="{{latitude}}"
  longitude="{{longitude}}"
  markers="{{markers}}"
  covers="{{covers}}"
  show-location
></map>

Page({
  data: {
    latitude: 23.099994,
    longitude: 113.324520,
    markers: [{
      id: 1,
      latitude: 23.099994,
      longitude: 113.324520,
      name: 'T.I.T 创意园'
    }],
    covers: [{
      latitude: 23.099994,
      longitude: 113.344520,
      iconPath: '/image/location.png'
    }, {
      latitude: 23.099994,
      longitude: 113.304520,
      iconPath: '/image/location.png'
    }]
  },
  onReady: function (e) {
    this.mapCtx = wx.createMapContext('myMap')
  },
  getCenterLocation: function () {
    this.mapCtx.getCenterLocation({
      success: function(res){
        console.log(res.longitude)
        console.log(res.latitude)
      }
    })
  }
})

And of course they have a <web-view>.

Inner Mechanics

From what I understand, it's all running in an iframe, Chrome/WeChat DevTools then hides the container, and all you see is the WXML layer.
When you look at the SDK's package contents, they make no real effort at hiding any of the inner mechanics: it's all HTML (of particular interest: /Applications/wechatwebdevtools.app/Contents/Resources/package.nw/html/standalone.html), CSS (of particular interest: /Applications/wechatwebdevtools.app/Contents/Resources/package.nw/static/app.css), and JavaScript (of particular interest: /Applications/wechatwebdevtools.app/Contents/Resources/package.nw/js/vendor/index.js).

Finally there is a local web server running that allows them to link from the online docs to local URLs like 127.0.0.1:32123/minicode/VBZ3Jim26zYu, which in turn allows them to open code samples from the docs that are ready to play with a click in WeChat DevTools. The web server luckily only runs when the Wechat Devtools are open.

Hello darkness, my old friend

Thomas Steiner — Mon, 05 Aug 2019 14:12:46 +0000

Overhyped or necessity? Learn everything about dark mode and how to support it to the benefit of your users!

(Originally published on https://web.dev/prefers-color-scheme/.)

Introduction

📚 I have done a lot of background research on the history and theory of dark mode, if you are only interested in working with dark mode, feel free to skip the introduction.

Dark mode before Dark Mode

Green screen (Source)

We have gone full circle with dark mode. In the dawn of personal computing, dark mode wasn’t a matter of choice, but a matter of fact: Monochrome CRT computer monitors worked by firing electron beams on a phosphorescent screen and the phosphor used in early CRTs was green. Because text was displayed in green and the rest of the screen was black, these models were often referred to as green screens.

Dark-on-white (Source)

The subsequently introduced Color CRTs displayed multiple colors through the use of red, green, and blue phosphors. They created white by activating all three phosphors simultaneously. With the advent of more sophisticated WYSIWYG desktop publishing, the idea of making the virtual document resemble a physical sheet of paper became popular.

The WorldWideWeb browser (Source)

This is where dark-on-white as a design trend started, and this trend was carried over to the early document-based web. The first ever browser, WorldWideWeb (remember, CSS wasn’t even invented yet), displayed webpages this way. Fun fact: the second ever browser, Line Mode Browser — a terminal-based browser — was green on dark. These days, web pages and web apps are typically designed with dark text on a light background, a baseline assumption that is also hard-coded in user agent stylesheets, including Chrome’s.

Smartphone used in bed (Source)

The days of CRTs are long over. Content consumption and creation has shifted to mobile devices that use backlit LCD or energy-saving AMOLED screens. Smaller and more transportable computers, tablets, and smartphones led to new usage patterns. Leisure tasks like web browsing, coding for fun, and high-end gaming frequently happen after-hours in dim environments. People even enjoy their devices in their beds at night-time. The more people use their devices in the dark, the more the idea of going back to the roots of light-on-dark becomes popular.

Why dark mode

Dark mode for aesthetic reasons

When people get asked why they like or want dark mode, the most popular response is that “it’s easier on the eyes,”_followed by _“it’s elegant and beautiful.” Apple in their Dark Mode developer documentation explicitly writes: “The choice of whether to enable a light or dark appearance is an aesthetic one for most users, and might not relate to ambient lighting conditions.”

👩‍🔬 Read up more on user research regarding why people want dark mode and how they use it.

System 7 CloseView (Source)

Dark mode as an accessibility tool

There are also people who actually need dark mode and use it as another accessibility tool, for example, users with low vision. The earliest occurrence of such an accessibility tool I could find is System7’s CloseView feature, which had a toggle for Black on White and White on Black. While System 7 supported color, the default user interface was still black-and-white.

These inversion-based implementations demonstrated their weaknesses once color was introduced. User research by Szpiro et al. on how people with low vision access computing devices showed that all interviewed users disliked inverted images, but that many preferred light text on a dark background. Apple accommodates for this user preference with a feature called Smart Invert, which reverses the colors on the display, except for images, media, and some apps that use dark color styles.

A special form of low vision is Computer Vision Syndrome, also known as Digital Eye Strain, which is defined as “the combination of eye and vision problems associated with the use of computers (including desktop, laptop, and tablets) and other electronic displays (e.g. smartphones and electronic reading devices).” It has been proposed that the use of electronic devices by adolescents, particularly at night time, leads to an increased risk of shorter sleep duration, longer sleep-onset latency, and increased sleep deficiency. Additionally, exposure to blue light has been widely reported to be involved in the regulation of circadian rhythm and the sleep cycle, and irregular light environments may lead to sleep deprivation, possibly affecting mood and task performance, according to research by Rosenfield. To limit these negative effects, reducing blue light by adjusting the display color temperature through features like iOS’ Night Shift or Android’s Night Light can help, as well as avoiding bright lights or irregular lights in general through dark themes or dark modes.

Dark mode power savings on AMOLED screens

Finally, dark mode is known to save a lot of energy on AMOLED screens. Android case studies that focused on popular Google apps like YouTube have shown that the power savings can be up to 60%. The video below has more details on these case studies and the power savings per app.

Activating dark mode in the operating system

Now that I have covered the background of why dark mode is such a big deal for many users, let’s review how you can support it.

Android Q dark theme settings

Operating systems that support a dark mode or dark theme typically have an option to activate it somewhere in the settings. On macOS X, it’s in the system preference’s General section and called Appearance (screenshot), and on Windows 10, it’s in the Colors section and called Choose your color (screenshot). For Android Q, you can find it under Display as a Dark Theme toggle switch (screenshot), and on iOS 13, you can change the Appearance in the Display & Brightness section of the settings (screenshot).

The `prefers-color-scheme` media query

One last bit of theory before I get going. Media queries allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and JavaScript. Media Queries Level 5 introduces so-called user preference media features, that is, a way for sites to detect the user's preferred way to display content.

☝️ An established user preference media feature is prefers-reduced-motion that lets you detect the desire for less motion on a page. I have written about prefers-reduced-motion before.

The prefers-color-scheme media feature is used to detect if the user has requested the page to use a light or dark color theme. It works with the following values:

no-preference: Indicates that the user has made no preference known to the system. This keyword value evaluates as false in the boolean context.
light: Indicates that the user has notified the system that they prefer a page that has a light theme (dark text on light background).
dark: Indicates that the user has notified the system that they prefer a page that has a dark theme (light text on dark background).

Supporting dark mode

Finding out if dark mode is supported by the browser

As dark mode is reported through a media query, you can easily check if the current browser supports dark mode by checking if the media query prefers-color-schemematches at all. Note how I don't include any value, but purely check if the media query alone matches.

if (window.matchMedia('(prefers-color-scheme)').media !== 'not all') {
 console.log('🎉 Dark mode is supported');
}

At the time of writing, prefers-color-scheme is supported on both desktop and mobile (where available) by Chrome and Edge as of version 76, Firefox as of version 67, and Safari as of version 12.1 on macOS and as of version 13 on iOS. For all other browsers, you can check the Can I use support tables.

There is a custom element <dark-mode-toggle>available that adds dark mode support to older browsers. I write about it further down in this article.

Dark mode in practice

Let’s finally see how supporting dark mode looks like in practice. Just like with the Highlander, with dark mode there can be only one: dark or light, but never both! Why do I mention this? Because this fact should have an impact on the loading strategy. Please don’t force users to download CSS in the critical rendering path that is for a mode they don’t currently use. To optimize load speed, I have therefore split my CSS for the example app that shows the following recommendations in practice into three parts in order to defer non-critical CSS:

style.css that contains generic rules that are used universally on the site.
dark.css that contains only the rules needed for dark mode.
light.css that contains only the rules needed for light mode.

Loading strategy

The two latter ones, light.css and dark.css, are loaded conditionally with a <link media> query. Initially, not all browsers will support prefers-color-scheme(detectable using the pattern above), which I deal with dynamically by loading the default light.css file via a conditionally inserted <link rel="stylesheet"> element in a minuscule inline script (light is an arbitrary choice, I could also have made dark the default fallback experience). To avoid a flash of unstyled content, I hide the content of the page until light.css has loaded.

<script>
 // If `prefers-color-scheme` is not supported, fall back to light mode.
 // In this case, light.css will be downloaded with `highest` priority.
 if (window.matchMedia('(prefers-color-scheme)').media === 'not all') {
 document.documentElement.style.display = 'none';
 document.head.insertAdjacentHTML(
 'beforeend',
 '<link rel="stylesheet" href="/light.css" onload="document.documentElement.style.display = ``">'
 );
 }
</script>
<!--
 Conditionally either load the light or the dark stylesheet. The matching file
 will be downloaded with `highest`, the non-matching file with `lowest`
 priority. If the browser doesn't support `prefers-color-scheme`, the media
 query is unknown and the files are downloaded with `lowest` priority (but
 above I already force `highest` priority for my default light experience).
-->
<link rel="stylesheet" href="/dark.css" media="(prefers-color-scheme: dark)">
<link rel="stylesheet" href="/light.css" media="(prefers-color-scheme: no-preference), (prefers-color-scheme: light)">
<!-- The main stylesheet -->
<link rel="stylesheet" href="/style.css">

Stylesheet architecture

I make maximum use of CSS variables, this allows my generic style.css to be, well, generic, and all the light or dark mode customization happens in the two other files dark.css and light.css. Below you can see an excerpt of the actual styles, but it should suffice to convey the overall idea. I declare two variables, -⁠-⁠color and -⁠-⁠background-color that essentially create a dark-on-light and a light-on-dark baseline theme.

/* light.css: 👉 dark-on-light */
:root {
 --color: rgb(5, 5, 5);
 --background-color: rgb(250, 250, 250);
}

/* dark.css: 👉 light-on-dark */
:root {
 --color: rgb(250, 250, 250);
 --background-color: rgb(5, 5, 5);
}

In my style.css, I then use these variables in the body { … } rule. As they are defined on the :root CSS pseudo-class—a selector that in HTML represents the <html> element and is identical to the selector html, except that its specificity is higher—they cascade down, which serves me for declaring global CSS variables.

/* style.css */
:root {
 color-scheme: light dark;
}

body {
 color: var(--color);
 background-color: var(--background-color);
}

In the code sample above, you will probably have noticed a property color-scheme with the space-separated value light dark.

Warning: The color-scheme property is still in development and it might not work as advertised, full support in Chrome will come later this year.

This tells the browser which color themes my app supports and allows it to activate special variants of the user agent stylesheet, which is useful to, for example, let the browser render form fields with a dark background and light text, adjust the scrollbars, or to enable a theme-aware highlight color. The exact details of color-scheme are specified in CSS Color Adjustment Module Level 1.

🌒 Read up more on what color-scheme actually does.

Everything else is then just a matter of defining CSS variables for things that matter on my site. Semantically organizing styles helps a lot when working with dark mode. For example, rather than -⁠-⁠highlight-yellow, consider calling the variable -⁠-⁠accent-color, as "yellow" may actually not be yellow in dark mode or vice versa. Below is an example of some more variables that I use in my example.

/* dark.css */
:root {
 --color: rgb(250, 250, 250);
 --background-color: rgb(5, 5, 5);
 --link-color: rgb(0, 188, 212);
 --main-headline-color: rgb(233, 30, 99);
 --accent-background-color: rgb(0, 188, 212);
 --accent-color: rgb(5, 5, 5);
}

/* light.css */
:root {
 --color: rgb(5, 5, 5);
 --background-color: rgb(250, 250, 250);
 --link-color: rgb(0, 0, 238);
 --main-headline-color: rgb(0, 0, 192);
 --accent-background-color: rgb(0, 0, 238);
 --accent-color: rgb(250, 250, 250);
}

Full example

In the following Glitch embed, you can see the complete example that puts the concepts from above into practice. Try toggling dark mode in your particular operating system’s settings and see how the page reacts.

Loading impact

When you play with this example, you can see why I load my dark.css and light.css via media queries. Try toggling dark mode and reload the page: the particular currently non-matching stylesheets are still loaded, but with the lowest priority, so that they never compete with resources that are needed by the site right now.

😲 Read up more on why browsers download stylesheets with non-matching media queries.

Site in light mode loads the dark mode CSS with lowest priority.

Site in dark mode loads the light mode CSS with lowest priority.

Site in default light mode on a browser that doesn’t support prefers-color-scheme loads the dark mode CSS with lowest priority.

Reacting on dark mode changes

Like any other media query change, dark mode changes can be subscribed to via JavaScript. You can use this to, for example, dynamically change the favicon of a page or change the <meta name="theme-color"> that determines the color of the URL bar in Chrome. The full example above shows this in action, in order to see the theme color and favicon changes, open the demo in a separate tab.

const darkModeMediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
 darkModeMediaQuery.addListener((e) => {
 const darkModeOn = e.matches;
 console.log(`Dark mode is ${darkModeOn ? '🌒 on' : '☀️ off'}.`);
 });

Dark mode best practices

Avoid pure white

A small detail you may have noticed is that I don’t use pure white. Instead, to prevent glowing and bleeding against the surrounding dark content, I choose a slightly darker white. Something like rgb(250, 250, 250) works well.

Re-colorize and darken photographic images

If you compare the two screenshots below, you will notice that not only the core theme has changed from dark-on-light to light-on-dark, but that also the hero image looks slightly different. My user research has shown that the majority of the surveyed people prefer slightly less vibrant and brilliant images when dark mode is active. I refer to this as re-colorization.

Hero image slightly darkened in dark mode.

Regular hero image in light mode.

Re-colorization can be achieved through a CSS filter on my images. I use a CSS selector that matches all images that don’t have .svg in their URL, the idea being that I can give vector graphics (icons) a different re-colorization treatment than my images (photos), more about this in the next paragraph. Note how I again use a CSS variable, so I can later on flexibly change my filter.

🎨 Read up more on user research regarding re-colorization preferences with dark mode.

As re-colorization is only needed in dark mode, that is, when dark.css is active, there are no corresponding rules in light.css.

/* dark.css */
--image-filter: grayscale(50%);

img:not([src*=".svg"]) {
 filter: var(--image-filter);
}

Customizing dark mode re-colorization intensities with JavaScript

Not everyone is the same and people have different dark mode needs. By sticking to the re-colorization method described above, I can easily make the grayscale intensity a user preference that I can change via JavaScript, and by setting a value of 0%, I can also disable re-colorization completely. Note that document.documentElementprovides a reference to the root element of the document, that is, the same element I can reference with the :rootCSS pseudo-class.

const filter = 'grayscale(70%)';
document.documentElement.style.setProperty('--image-filter', value);

Invert vector graphics and icons

For vector graphics — that in my case are used as icons that I reference via <img> elements—I use a different re-colorization method. While research has shown that people don't like inversion for photos, it does work very well for most icons. Again I use CSS variables to determine the inversion amount in the regular and in the :hover state.

Icons are inverted in dark mode.

Regular icons in light mode.

Note how again I only invert icons in dark.css but not in light.css, and how :hover gets a different inversion intensity in the two cases to make the icon appear slightly darker or slightly brighter, dependent on the mode the user has selected.

/* dark.css */
--icon-filter: invert(100%);
--icon-filter_hover: invert(40%);

img[src*=".svg"] {
 filter: var(--icon-filter);
}


/* light.css */
--icon-filter_hover: invert(60%);

/* style.css */
img[src*=".svg"]:hover {
 filter: var(--icon-filter_hover);
}

Use `currentColor` for inline SVGs

For inline SVG images, instead of using inversion filters, you can leverage the currentColor CSS keyword that represents the value of an element's color property. This lets you use the color value on properties that do not receive it by default. Conveniently, if currentColor is used as the value of the SVG fill or strokeattributes, it instead takes its value from the inherited value of the color property. Even better: this also works for <svg><use href="…"></svg>, so you can have separate resources and currentColor will still be applied in context. Please note that this only works for inline or <use href="…"> SVGs, but not SVGs that are referenced as the src of an image or somehow via CSS. You can see this applied in the demo below.

<!-- Some inline SVG -->
<svg xmlns="http://www.w3.org/2000/svg"
 stroke="currentColor"
>
 […]
</svg>

Smooth transitions between modes

Switching from dark mode to light mode or vice versa can be smoothed thanks to the fact that both color and background-color are animatable CSS properties. Creating the animation is as easy as declaring two transitions for the two properties. The example below illustrates the overall idea, you can experience it live in thedemo.

body {
 --duration: 0.5s;
 --timing: ease;

color: var(--color);
 background-color: var(--background-color);

transition:
 color var(--duration) var(--timing),
 background-color var(--duration) var(--timing);
}

Art direction with dark mode

While for loading performance reasons in general I recommend to exclusively work with prefers-color-scheme in the media attribute of <link> elements (rather than inline in stylesheets), there are situations where you actually may want to work with prefers-color-scheme directly inline in your HTML code. Art direction is such a situation. On the web, art direction deals with the overall visual appearance of a page and how it communicates visually, stimulates moods, contrasts features, and psychologically appeals to a target audience.

With dark mode, it’s up to the judgment of the designer to decide what is the best image at a particular mode and whether re-colorization of images is maybe not good enough. If used with the <picture> element, the <source> of the image to be shown can be made dependent on the media attribute. In the example below, I show the Western hemisphere for dark mode, and the Eastern hemisphere for light mode or when no preference is given, defaulting to the Eastern hemisphere in all other cases. This is of course purely for illustrative purposes. Toggle dark mode on your device to see the difference.

<picture>
 <source srcset="western.webp" media="(prefers-color-scheme: dark)">
 <source srcset="eastern.webp" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)">
 `<img src="eastern.webp">
</picture>

Dark mode, but add an opt-out

As mentioned in the why dark mode section above, dark mode is an aesthetic choice for most users. In consequence, some users may actually like to have their operating system UI in dark, but still prefer to see their webpages the way they are used to seeing them. A great pattern is to initially adhere to the signal the browser sends through prefers-color-scheme, but to then optionally allow users to override their system-level setting.

The `<dark-mode-toggle>` custom element

You can of course create the code for this yourself, but you can also just use a ready-made custom element (web component) that I have created right for this purpose. It’s called <dark-mode-toggle> and it adds a toggle (dark mode: on/off) or a theme switcher (theme: light/dark) to your page that you can fully customize. The demo below shows the element in action (oh, and I have also 🤫 silently snuck it in all of the other examples above).

<dark-mode-toggle
 legend="Theme Switcher"
 appearance="switch"
 dark="Dark"
 light="Light"
 remember="Remember this"
></dark-mode-toggle>

<dark-mode-toggle> in light mode.

<dark-mode-toggle> in dark mode.

Try clicking or tapping the dark mode controls in the upper right corner in the demo below. If you check the checkbox in the third and the fourth control, see how your mode selection is remembered even when you reload the page. This allows your visitors to keep their operating system in dark mode, but enjoy your site in light mode or vice versa.

GoogleChromeLabs / dark-mode-toggle

A custom element that allows you to easily put a Dark Mode 🌒 toggle or switch on your site:

`<dark-mode-toggle>` Element

A custom element that allows you to easily put a Dark Mode 🌒 toggle or switch on your site, so you can initially adhere to your users' preferences according to prefers-color-scheme but also allow them to (optionally permanently) override their system setting for just your site.

📚 Read all(!) about dark mode in the related article Hello Darkness, My Old Friend.

Installation

From npm:

npm install --save dark-mode-toggle

In the browser:

import * as DarkModeToggle from 'https://cdn.pika.dev/dark-mode-toggle';

import * as DarkModeToggle from 'https://unpkg.com/dark-mode-toggle';

Usage

⚠️ The custom element assumes that you have organized your CSS in different files that you load conditionally based on the media attribute in the stylesheet's corresponding link element. This is a great performance pattern as you don't force people to download CSS that they don't need based on their current theme preference, yet non-matching…

View on GitHub

Conclusions

Working with and supporting dark mode is fun and opens up new design avenues. For some of your visitors it can be the difference between not being able to handle your site and being a happy user. There are some pitfalls and careful testing is definitely required, but dark mode is definitely a great opportunity for you to show that you care about all of your users. The best practices mentioned in this post and helpers like the <dark-mode-toggle> custom element should make you confident in your ability to create an amazing dark mode experience. Let me know on Twitterwhat you create and if this post was useful or also suggestions for improving it. Thanks for reading! 🌒

Acknowledgements

The prefers-color-scheme media feature, the color-scheme CSS property, and the related meta tag are the implementation work of 👏 Rune Lillesveen. Rune is also a co-editor of the CSS Color Adjustment Module Level 1spec. I would like to 🙏 thank Lukasz Zbylut, Rowan Merewood, Chirag Desai, and Rob Dodson for their thorough reviews of this article. The loading strategy is the brainchild of Jake Archibald. Emilio Cobos Álvarez has pointed me to the correct prefers-color-schemedetection method. The tip with referenced SVGs and currentColor came from Timothy Hatcher. Finally, I am thankful to the many anonymous participants of the various user studies that have helped shape the recommendations in this article. Hero image by Nathan Anderson.

Why Browsers Download Stylesheets With Non-Matching Media Queries

Thomas Steiner — Thu, 08 Nov 2018 17:24:41 +0000

(Originally posted on blog.tomayac.com/2018/11/08/why-browsers-download-stylesheets-with-non-matching-media-queries-180513.)

The other day, I read an article by Dario Gieselaar on Optimizing CSS by removing unused media queries. One of the core ideas is that you can use the media attribute when including your stylesheets like so:

<link href="print.css" rel="stylesheet" media="print">
<link href="mobile.css" rel="stylesheet" media="screen and (max-width: 600px)">

In the article, Dario links to Scott Jehl's CSS Downloads by Media Query test suite where Scott shows how browsers would still download stylesheets even if their media queries are non-matching.

I pointed out that the priority of these downloads is Lowest, so they're at least not competing with core resources on the page:

At first sight this still seemed suboptimal, and I thought that even if the priority is Lowest, maybe the browser shouldn't trigger downloads at all. So I did some research, and, surprise, it turns out that the CSS spec writers and browser implementors are actually pretty darn smart about this:

The thing is, the user could always decide to resize their window (impacting width, height, aspect ratio), to print the document, etc., and even things that at first sight seem static (like the resolution) can change when a user with a multi-screen setup moves a window from say a Retina laptop screen to a bigger desktop monitor, or the user can unplug their mouse, and so on.

Truly static things that can't change (a TV device can't suddenly turn into something else) are actually being deprecated in Media Queries Level 4 (see the yellow note box); and the recommendation is to rather target media features instead (see the text under the red issue box).

Finally, even invalid values like media="nonsense" still need to be considered, according to the ignore rules in the spec.

So long story short, browsers try to be as smart as possible by applying priorities, and Lowest is a reasonable value for the cases in Scott's test.