How to Inspect and Control CSS light-dark() in Safari Web Inspector

Creating responsive interfaces that transition smoothly between light and dark visual themes historically required extensive CSS media queries (@media (prefers-color-scheme: dark)) duplicated across multiple selectors. Modern CSS introduces the native light-dark() colour function, allowing developers to define contextual colour tokens directly within a single declaration. Safari on macOS offers integrated tooling within its Web Inspector to inspect computed colour spaces, override colour schemes on a per-element basis, and simulate appearance environments without changing system-wide preferences.

Understanding the CSS light-dark() Function

The light-dark() function accepts two colour arguments: the first is rendered when the computed colour scheme is light, and the second is rendered when the scheme is dark:

:root {
  color-scheme: light dark;
  --bg-primary: light-dark(#ffffff, #121212);
  --text-primary: light-dark(#1f2937, #f9fafb);
}

For light-dark() to resolve correctly, an ancestor element or the :root selector must explicitly declare the color-scheme property. If color-scheme is omitted or set to normal, the browser defaults to the light value regardless of the user’s operating system theme.

Prerequisites and Inspector Setup

To access developer features in Safari on macOS:

1. Launch Safari and open Settings (or press Cmd + ,).
2. Click on the Advanced tab.
3. Check the box labelled Show features for web developers (in older macOS versions: Show Develop menu in menu bar).
4. Right-click on any element within a webpage and select Inspect Element to launch Safari Web Inspector.

Simulating Appearance Modes in Safari Web Inspector

Rather than toggling your entire macOS appearance between Light and Dark in System Settings, Safari allows instantaneous mode switching within the inspector interface:

1. Open the Elements tab in Safari Web Inspector.
2. Locate the device and preference emulation toolbar at the top of the Elements or Console pane.
3. Find the Appearance Emulation icon (depicted as a half-filled circle representing sun/moon states).
4. Click the icon to cycle between:
   • System Default: Inherits your current macOS appearance.
   • Force Light Appearance: Evaluates color-scheme: light and renders the first argument in light-dark().
   • Force Dark Appearance: Evaluates color-scheme: dark and renders the second argument in light-dark().
5. Observe how the rendered page elements and computed CSS values update instantaneously.

Inspecting Resolved light-dark() Properties in the Styles Pane

When selecting an element that employs light-dark(), Safari Web Inspector provides visual indicators to distinguish which branch of the function is actively applied:

1. In the Elements tree, select the target DOM node.
2. Inspect the Styles sidebar on the right.
3. Examine the property rule (e.g., background-color: light-dark(#ffffff, #1a1a1a);).
4. Safari highlights the active colour token while dimming the inactive token, making it immediately apparent whether the light or dark branch was evaluated.
5. Click on the adjacent colour swatch next to the declaration to open the Web Inspector Colour Picker. You can adjust either colour token interactively, convert colour spaces (sRGB, Display P3, OKLCH), and verify contrast ratios against adjacent background layers.

Debugging Scoped color-scheme Overrides

A major advantage of light-dark() is that it respects locally scoped color-scheme properties. For instance, a dark card container can be embedded within an otherwise light page layout:

.dark-card {
  color-scheme: dark;
  background-color: light-dark(#f3f4f6, #1f2937);
  color: light-dark(#111827, #f9fafb);
}

To verify scoped resolution in Safari:

1. Select the child container in the Elements DOM tree.
2. Navigate to the Computed styles tab in the sidebar.
3. Filter for color-scheme to confirm that the computed value shows dark rather than inheriting light from :root.
4. Check the color and background-color properties to verify that the dark variant values were assigned to the element.

Common Pitfalls and Best Practices

• Missing color-scheme Declaration: If light-dark() fails to switch when toggling emulation, confirm that color-scheme: light dark; is declared on the :root or html selector.
• Wide Gamut Colours: Combine light-dark() with modern colour notations such as oklch() to ensure vibrant, consistent gamut mapping across Apple Retina displays.
• Automated Audits: Use the Audit tab within Safari Web Inspector to test for accessibility contrast failures in both light and dark operational states.