Home » Color Modes

Color Modes

Boilerplate color modes are built as a dual-token system. Light and dark values are configured separately, emitted as runtime CSS custom properties, and then applied through root HTML state classes and Bootstrap 5’s data-bs-theme attribute.

Primary Files

  • config.php – PHP-side color mode configuration
  • assets/js/color_mode.js – client-side mode resolution, toggle behavior, and localStorage handling
  • assets/sass/parent_theme/variables.scss – configured light/dark source values
  • assets/sass/parent_theme/color_mode.scss – emits runtime CSS custom properties per mode
  • lib/navbar_special_items.php – WordPress menu-driven color mode toggle controls

Configured Modes

BP_COLOR_MODE controls the theme’s configured mode.

  • system – use browser/OS preference unless the visitor has saved a local override
  • light – force light mode and ignore browser/local visitor preference
  • dark – force dark mode and ignore browser/local visitor preference

File: config.php

System Mode

System mode resolves through prefers-color-scheme. If the visitor has no saved local preference, Boilerplate follows the browser/OS light or dark preference.

File: assets/js/color_mode.js

Use this for: default behavior that respects visitor device settings.

LocalStorage Override

When BP_COLOR_MODE is system, visitors may override the resolved mode. Boilerplate stores the selected light or dark value in localStorage.

Config: BP_COLOR_MODE_STORAGE_KEY
Default key: bp_color_mode
File: assets/js/color_mode.js

Forced Mode Behavior

When BP_COLOR_MODE is set to light or dark, the mode is forced. Local visitor overrides are ignored and color mode toggles are hidden/disabled.

File: config.php

Use this for: sites that should always render in a single visual mode.

Early Root State

Boilerplate applies color mode state early with an inline configuration script. This sets the root classes and attributes before the full color mode JavaScript initializes.

  • bp_theme_system
  • bp_theme_light
  • bp_theme_dark
  • bp_theme_resolved_light
  • bp_theme_resolved_dark
  • data-bp-color-mode
  • data-bp-color-mode-resolved
  • data-bs-theme

Use this for: avoiding mode mismatch while the page is loading.

Bootstrap 5 Integration

Boilerplate feeds the resolved mode into Bootstrap 5 by setting data-bs-theme on the root element.

data-bs-theme="light"
data-bs-theme="dark"

Use this for: keeping Bootstrap components aligned with Boilerplate’s active color mode.

Dual Color Variables

Boilerplate maintains separate configured values for light and dark mode. These values live in the theme variable layer and are emitted into runtime CSS custom properties by color_mode.scss.

Source values: assets/sass/parent_theme/variables.scss
Runtime output: assets/sass/parent_theme/color_mode.scss

Use this for: configuring complete light/dark equivalents instead of patching isolated component colors.

CSS Variables Per Mode

color_mode.scss emits mode-specific CSS variables for body colors, content backgrounds, borders, links, neutral links, buttons, inputs, blockquotes, post headers, navbar colors, header colors, footer colors, breadcrumbs, article summaries, pagination, post meta, sharing links, gravatars, comments, widgets, calendars, media players, galleries, and lightbox-related colors.

Light mixin: bp_color_mode_vars_light
Dark mixin: bp_color_mode_vars_dark

Rule: components should use runtime tokens such as var( --bp-body-color ), var( --bp-theme-border-color ), var( --bp-link-color ), var( --bp-button-bg-color ), and var( --bp-input-bg-color ) instead of hardcoded mode-specific colors.

Menu Toggle Links

Color mode toggles are placed through WordPress Custom Link menu items. Boilerplate converts supported URLs into accessible toggle controls.

#bp-color-mode-toggle
#bp-color-mode-toggle-with-text

File: lib/navbar_special_items.php

Related config: BP_COLOR_MODE_TOGGLE_ENABLED

Behavior: toggles render with data-bp-color-mode-toggle, accessible labels, Bootstrap Icon markup, and optional visible text.

Recommended Color Flow

  1. Set the configured mode in config.php.
  2. Configure light/dark source values in variables.scss.
  3. Emit runtime mode tokens through color_mode.scss.
  4. Use runtime CSS custom properties in component styles.
  5. Let assets/js/color_mode.js resolve system/local/forced behavior.
  6. Let data-bs-theme keep Bootstrap aligned with the resolved mode.
© 2026 Boilerplate