Repository navigation
Dark Mode
Aegis includes built-in dark mode support that inverts the color scheme for comfortable viewing in low-light environments. Dark mode is controlled by applying the is-style-dark class to the <body> element.
Dark mode in Aegis uses a class-based toggle mechanism:
- Light mode (default): The site renders with the standard color palette defined in the active style variation.
-
Dark mode: When the
is-style-darkclass is present on the<body>element, CSS custom properties are remapped to their dark equivalents.
This approach ensures that:
- All design tokens automatically adapt to dark mode.
- Block patterns and templates do not require separate dark versions.
- Style variations maintain their character in both modes.
To enable dark mode site-wide:
- Open the Site Editor (Appearance → Editor).
- Edit the template that wraps your content.
- Select the outermost Group block.
- In the Advanced section of the block settings, add
is-style-darkto the Additional CSS class(es) field. - Save the template.
To enable dark mode on individual pages:
- Edit the page in the block editor.
- Select the root Group block or add one wrapping all content.
- Add
is-style-darkto the Additional CSS class(es) field. - Update the page.
Aegis supports a user-facing dark mode toggle that allows visitors to switch between light and dark modes:
- The toggle button adds or removes the
is-style-darkclass on the<body>element via JavaScript. - The visitor preference is stored in
localStoragefor persistence across page loads. - You can include the dark mode toggle in the header template part.
When dark mode is active, the color palette inverts intelligently:
| Token | Light Mode | Dark Mode |
|---|---|---|
| Background | Neutral-0 (white) | Neutral-950 (near-black) |
| Foreground | Neutral-950 (near-black) | Neutral-0 (white) |
| Surface | Neutral-50 | Neutral-900 |
| Border | Neutral-200 | Neutral-700 |
| Muted text | Neutral-500 | Neutral-400 |
| Primary accent | Zinc-600 | Zinc-400 |
The full color system, including Success, Warning, and Error tokens, adjusts accordingly to maintain contrast ratios and readability.
Aegis can detect the visitor operating system dark mode preference using the prefers-color-scheme media query:
@media (prefers-color-scheme: dark) {
body:not(.is-style-light) {
/* Dark mode custom properties applied */
}
}When automatic detection is enabled, the site follows the system preference unless the visitor explicitly toggles the mode.
All 60 style variations support dark mode. Each variation defines both light and dark color mappings, so switching to dark mode preserves the character of the chosen variation (for example, the "Ocean" variation will use dark navy backgrounds rather than generic dark gray).
Dark mode in Aegis maintains WCAG 2.1 AA contrast requirements:
- Text contrast ratios remain above 4.5:1 for normal text.
- Large text maintains at least 3:1 contrast.
- Interactive elements retain visible focus indicators.
- Color is never the sole indicator of meaning.
You can apply dark mode to individual sections rather than the entire page:
- Select a Group block or container section.
- Add
is-style-darkto the Additional CSS class(es) field. - That section will render with dark mode colors while the rest of the page remains in light mode.
This technique is useful for creating visual contrast between sections, such as a dark hero section followed by light content.
If you do not want dark mode available on your site:
- Do not add the
is-style-darkclass to any templates or blocks. - Remove the dark mode toggle from the header template part if present.
- Visitors will always see the light mode regardless of their system preferences.
To override specific dark mode colors:
- Open Appearance → Editor → Styles.
- Make color adjustments in the Styles panel.
- These overrides apply to both light and dark modes by default.
For dark-mode-specific overrides, you can use the Additional CSS section or a custom stylesheet that targets the .is-style-dark class:
.is-style-dark {
--wp--preset--color--primary-500: #custom-dark-value;
}The dark mode system works through CSS custom property reassignment. When the is-style-dark class is present:
- Background tokens are swapped to dark values.
- Foreground tokens are swapped to light values.
- Surface, border, and accent tokens adjust to maintain visual hierarchy.
- Shadow tokens adjust opacity for dark backgrounds.
- Gradient tokens may adjust to dark-appropriate versions.
No JavaScript framework or library is required — the mechanism is pure CSS with a minimal script for toggle interaction and preference storage.
- color-palette — Understand the full color system and its light/dark mappings.
- style-variations — See how variations look in both modes.
- global-styles — Customize colors for light and dark modes.
- accessibility — Learn about the accessibility features in Aegis.
Aegis version 1.0.0 | GitHub Repository | Report an Issue | Atmostfear Entertainment
License: GPL-2.0-or-later