How to design for dark mode

Apply the Sitka colour token set correctly in dark contexts. This guide covers surface stepping, elevation, contrast validation, and the most common dark-mode mistakes.

Objective

By the end of this guide you will be able to apply the Sitka dark-mode token set consistently, validate contrast pairings in both themes, and avoid the four most common dark-mode design failures.

Use tokens — never raw hex values

Every colour in Sitka is available as a CSS custom property. When you use a token, the dark and light values swap automatically. When you hardcode a hex, they don't.

✗ Avoid

color: #ffffff;

✓ Use

color: rgb(var(--text-primary));

Related: Design tokens lists every available token. The Colour foundations page shows how they map to the palette.

Use surface stepping for elevation

In dark mode, shadows are barely visible. Elevation is communicated through surface lightness instead. Each surface token is approximately 5–10 lightness points brighter than the one below it.

--background

Page canvas

#09090c

--surface

Cards, panels

#0d0d11

--surface-raised

Dropdowns, popovers

#16161c

--surface-hover

Hover fill

#202028

Validate contrast in both modes

A colour pair that passes in light mode may fail in dark mode, and vice versa. Always check both.

1.Open your design in Figma with the Stark plugin, or the browser with Polypane.
2.Toggle the interface to dark mode.
3.Run a contrast check on every text/background pairing that uses a non-standard token.
4.Confirm all body text meets 4.5:1 (AA), all large text meets 3:1 (AA Large).
5.Toggle back to light mode and repeat.

The Contrast foundations page lists every pre-validated token pairing and its ratio. Use those pairings and you won't need to check.

Don't invert icons or images

Icons that use currentColor adapt automatically. Raster images and logos with dark fills need a white or light background container in dark mode — don't CSS-invert them, as this breaks colour accuracy.

✗ Avoid

filter: invert(1);

✓ Use

<span class="rounded-full bg-white">…</span>

Test with a real device in dark mode

Screens vary. OLED displays have true black, LCD panels have a grey black. Always test on a real device, not just the browser simulator.

—Enable dark mode in System Preferences / Display Settings.
—Open your app in Safari or the native shell.
—Check that surfaces are distinct — background, surface, and surface-raised should read as three separate depths.
—Check that text reads comfortably at arm's length — tertiary text at small sizes is the most common failure point.

Color Contrast Design tokens How to ensure colour is accessible