Dark mode toggles that preserve readable contrast

Dark mode can reduce glare on phones and laptops, but reversing light and dark colours is not an implementation. Knowing how to implement a dark mode toggle without breaking contrast means treating theme choice as an accessibility decision that supports every state, not merely a visual preference.

Australian users move between bright Perth sunlight, regional travel and long evenings in Sydney or Melbourne. A mobile-first local market makes legible controls and quick responses particularly important, while varied home, work and outdoor viewing conditions expose weak palettes quickly.

The Australian Government Digital Service Standard places accessibility within digital delivery expectations, and WCAG 2.2 AA provides a useful benchmark. Apply its requirements to both themes, including links, form errors, focus indicators and text embedded in images, while ensuring inactive controls remain distinguishable.

Minimal interfaces benefit from a restrained visual system. Easy navigation, clear layouts and readable typography remain valuable when colours change, so the toggle should stay predictable while the interface continues to explain itself without extra decoration.

Begin with semantic colour tokens

Begin with semantic tokens rather than raw colours. Define roles such as --surface-page, --text-primary, --text-muted, --border, --accent and --focus-ring, then map them to light and dark values. Components keep stable rules while only the mappings change. These examples are a starting point, not a substitute for testing.

:root {
  color-scheme: light;
  --surface-page: #ffffff;
  --surface-raised: #f4f6f8;
  --text-primary: #172033;
  --text-muted: #526071;
  --accent: #0759c7;
  --on-accent: #ffffff;
  --border: #667085;
  --focus-ring: #0b63ce;
}

[data-theme="dark"] {
  color-scheme: dark;
  --surface-page: #11151b;
  --surface-raised: #1a212b;
  --text-primary: #f1f5f9;
  --text-muted: #c3ccd8;
  --accent: #8bbcff;
  --on-accent: #11151b;
  --border: #9aa4b2;
  --focus-ring: #9cc5ff;
}

Only palette mappings should differ between themes. Avoid applying filter: invert() to the document: images, icons and brand assets can become wrong, while filtered text may render inconsistently. Shadows also need dark-theme counterparts because a shadow that lifts a white card may disappear on a near-black page.

Make preference handling predictable

Use the operating-system preference as the default, with light and dark as explicit overrides. Apply the selected theme before first paint to prevent a flash, using prefers-color-scheme for the default. Store an explicit choice locally when storage is available, and keep a safe fallback if storage is blocked.

The control should be a real button with a stable accessible name and aria-pressed state. Keyboard activation and a visible focus ring are mandatory. Use at least 24 by 24 CSS pixels under WCAG 2.2 and consider a 44 by 44 target for comfortable touch. A label such as “Dark mode” can remain constant while the pressed state communicates the selection.

Theme changes must survive navigation and reloads without depending on remote scripts. The restrained hierarchy demonstrated by the minimal site layout shows why an obvious control, stable type and generous spacing can matter more than elaborate effects.

Measure contrast in every state

Measure contrast rather than judging it by eye. WCAG 2.2 AA generally requires at least 4.5:1 for normal text, 3:1 for large text, and 3:1 for essential non-text elements such as input boundaries and focus indicators. Check each foreground against the exact background where it appears.

Dark palettes often fail where muted text becomes dim, borders merge into surfaces, or hover states lose definition. Check body copy, placeholders, validation messages, links, icons, charts and selected controls independently. A token can pass on the page background but fail on a raised card or coloured banner.

Pure black and white can create glare, halation and visual fatigue. Near-black neutrals with off-white text may feel steadier, but comfort is not proof of compliance: calculate the ratios and inspect the interface at 200% and 400% zoom. Never rely on colour alone to convey an error or state.

Design for media and brand exceptions

Warm palettes need particular care. The history of coffee's global journey offers a useful parallel: familiar colours acquire new meanings as they travel. In Melbourne's flat-white culture and Australia's broader café scene, a cream or brown accent may feel familiar on a light menu yet become muddy against a dark interface.

Logos, product photography, charts, maps, QR codes and illustrations should be deliberate exceptions rather than automatically inverted. Supply dark variants where the brand permits it, or place assets on a stable light panel so their original colours and labels remain clear.

Third-party widgets and embedded media can override the page palette. Use provider-supported theme parameters where available, test iframe content separately, and ensure overlays, tooltips and payment messages inherit readable colours. Canvas elements and CSS-drawn diagrams need their own palette checks.

Test across devices and viewing conditions

Run a structured test matrix across iOS and Android phones, common desktop browsers, keyboard-only use and screen readers. Include forced-colour settings, increased contrast, reduced motion and zoom. Australian viewing conditions matter: check a page in harsh Perth daylight, a dim Sydney evening and a bright Melbourne café screen.

Include people with different visual needs, especially older users and users with low vision. Automated checks can find token mistakes, while manual review is still needed for halation, hover states, chart meaning and the order in which assistive technology announces the toggle.

Use one consistent matrix for each theme and record the computed foreground, background and ratio. The following comparison turns the key decisions into release criteria:

Element Light mode Dark mode Release check
Body text 4.5:1 minimum 4.5:1 minimum Test each surface
Large text and graphics 3:1 minimum 3:1 minimum Check every state
Borders and focus 3:1 adjacent 3:1 adjacent Verify keyboard use
Secondary text 4.5:1 if meaningful 4.5:1 if meaningful Avoid opacity-only fading
Links and errors 4.5:1 plus a cue 4.5:1 plus a cue Test hover and focus

Apply a resilient release checklist

Roll the feature out in stages so regressions are visible before every page changes. Add semantic tokens first, then the persisted preference, followed by an audit of assets and interactive states. A release owner should retain the contrast results and record any documented exceptions.

A release is complete only when both themes remain understandable in changing Australian viewing conditions, every essential control is reachable, and the saved preference behaves consistently across the site.