This guide explains how to set up light and dark mode color palettes for your Discourse site’s theme. It covers per-theme configuration, palette assignment, and user interface considerations.
Required user level: Administrator
Configuring distinct light and dark mode color palettes allows you to present your Discourse community in a way that aligns with your brand, improves accessibility, and gives your users control over their viewing experience. The recent improvements to Discourse’s theming system let you assign a preferred light and dark palette to each theme, and allow users to choose their desired appearance.
Summary
This guide covers:
- Understanding light and dark mode palette assignments
- Assigning light and dark color palettes to a theme
- Managing your site’s color palettes
- Understanding user-facing options
- Best practices for palette use and accessibility
Understanding light and dark mode palette assignments
Discourse themes support explicit assignment of both a “light” and a “dark” color palette. This way, any theme can automatically switch based on the user’s system setting, or let the user choose a preferred mode, while maintaining your preferred brand colors.
Assigning light and dark palettes to a theme
To configure your theme’s color palettes:
-
Go to Admin > Appearance > Themes & components (
/admin/customize/themes) -
Click on the theme you want to edit.
-
In the theme settings, locate the Color palettes section.
-
For both Color palette and Dark color palette, select the palette you want to use.
-
Click Save at the bottom of the theme settings page.
This ensures your site’s theme will use the correct palette for both light and dark mode users. Note that other user-selectable palettes can still be selected by your members, but the ones you set here will be the defaults.
Managing your color palettes
All available color palettes (and their linked assignments) can be managed centrally:
-
Navigate to Admin > Appearance > Color palettes (
/admin/customize/colors) -
Here you can edit, add, or remove palettes, mark them as user-selectable, and assign them to as your theme’s default light and dark palettes.
User-facing options
User preferences
Users can choose their preferred mode for viewing the site:
-
Go to User Preferences > Interface
-
In the “Color palette” section members can select their preferred light and dark palettes, as well as the mode they would like to use: Light, Dark, Auto:
If “Auto” is selected, Discourse will adapt to the user’s system color scheme preference.
Best practices
- Brand consistency: Customize palettes to match your branding for both modes. Keep core colors consistent but adjust for contrast and readability.
- Accessibility: Ensure color contrast ratios meet WCAG guidelines (this tool may help), especially in dark mode, where some colors may appear muted.
- Test on multiple devices: Check appearance in both modes, across devices and browsers.
- Logo assets: You can upload separate logos for light and dark modes in Admin > Appearance > Logos.
- Keep palette count manageable: Offer only the palettes users need or feel will be reasonable.
FAQs
Can I have more than one dark or light palette?
Yes, but it’s recommended to keep one main palette for each to reduce confusion. Assign only the primary palettes to themes for user selection.
Can I force everyone to use only light (or only dark) mode?
You can do this by setting the same palette as the default light and dark palettes, and ensuring that no other palettes are user-selectable.
Will custom theme components automatically adjust colors?
If they use Discourse’s CSS color variables (e.g., --primary, --secondary), they will inherit the palette. It’s best to avoid hardcoded colors in custom CSS.
Does palette switching change the whole theme, or just colors?
Only color variables change. Structure, fonts, and layout remain the same when changing color palettes.