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.
- Use one semantic token set for components and avoid hard-coded component colours.
- Respect the system preference until the user chooses, then persist that choice locally.
- Apply the theme before first paint and update
color-schemefor native controls. - Verify normal, hover, focus, active, selected, error and disabled states.
- Supply approved dark variants for logos, images, charts, maps and embeds.
- Test keyboard use, screen readers, zoom, forced colours and device sizes.
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.