Dark Mode

Overview

The dark mode system includes:

• Auto-Detection - Automatically follows browser/system dark mode preference
• Manual Toggle - Floating button for users to switch modes
• Session Persistence - Manual choice is remembered during the browser session
• Comprehensive Styling - Applies to all route pages, maps, filters, and cards

Admin Settings

Navigate to Routes → Config → Styles tab to find the Dark Mode settings.

Enable Dark Mode

Default: Enabled

This master toggle enables or disables the entire dark mode system:

• Checked - Users can use dark mode
• Unchecked - Site always uses light mode

Show Dark Mode Toggle

Default: Enabled

Controls whether the floating toggle button appears on the frontend:

• Checked - Toggle button visible in top-right corner
• Unchecked - No toggle button (auto-detection only)

Follow Browser Preference

Default: Enabled

Enables automatic detection of the user's browser/system preference:

• Checked - Automatically use dark mode if user's system is set to dark
• Unchecked - Default to light mode unless manually toggled

How It Works for Users

Default Behaviour (No Manual Toggle)

When a user first visits your site:

1. The plugin checks their browser/system dark mode preference
2. If their system is set to dark mode, the site displays in dark mode
3. If their system is set to light mode, the site displays in light mode
4. No preference is stored - the plugin simply follows the system setting

After Manual Toggle

When a user clicks the toggle button:

1. Their choice is saved to the browser's session storage
2. This choice persists across page navigation within the session
3. The manual choice overrides the system preference
4. When the browser closes, the preference is cleared

Toggle Button Appearance

• Position: Fixed in the top-right corner of the screen
• In Light Mode: Shows a moon icon (click to switch to dark)
• In Dark Mode: Shows a sun icon (click to switch to light)
• Hover Effect: Button scales slightly with a shadow

What Changes in Dark Mode

Dark mode applies comprehensive styling across all plugin elements:

Affected Elements

• Route filter/search page
• Route group pages
• Single route information pages
• Route cards and lists
• Maps and interactive elements
• Filter buttons and controls
• Tables and data displays
• Weather overlays and controls

Colour Scheme

Troubleshooting

Dark Mode Not Showing

• Check that "Enable Dark Mode" is ticked in Routes → Config → Styles
• Verify the dark mode CSS and JavaScript files are loading (check browser developer tools)
• Check for CSS conflicts with your WordPress theme
• Clear your browser cache

Toggle Button Not Visible

• Check that "Show Dark Mode Toggle" is ticked in the settings
• Check if the button is hidden behind other elements (z-index conflict)
• Inspect the page to see if the button exists in the DOM

Theme Not Persisting

• Session storage is designed to reset when the browser closes - this is expected behaviour
• If it's not persisting during a session, check if session storage is enabled in the browser
• Private/incognito mode may behave differently

Colours Look Wrong

• Check if your theme's CSS is overriding the dark mode variables
• Ensure colour values in the configuration are valid CSS colours

Accessibility

The dark mode feature is built with accessibility in mind:

• ARIA Labels: Toggle button includes proper accessibility labels
• Focus Indicators: Visible focus states are maintained in dark mode
• Reduced Motion: Respects the prefers-reduced-motion setting
• Colour Contrast: All text meets WCAG AA standards (minimum 4.5:1 contrast ratio)