BuddyX
Get BuddyX Pro

Recipe: Brand your dark mode

Free & Pro

What you'll build: a dark-mode version of your site that reflects YOUR brand (not the default midnight-blue palette). Custom dark backgrounds, custom dark brand accent, a dark-mode-appropriate version of your logo.

Time: ~30 minutes Prerequisites:

  • BuddyX Pro 5.1.0+ activated
  • Your brand colors decided (you'll need 2-3 hex values)
  • A dark-mode-friendly version of your logo (a light-colored version of your brand mark - see Step 4 if you don't have one yet)

What "branding dark mode" actually means

BuddyX Pro 5.1.0 ships a complete dark palette out of the box - a coordinated midnight-blue look (#1A1A2E page bg, #E94560 accent, etc.). Most sites can turn dark mode on with one toggle and it works.

But the default dark palette is brand-neutral. If you have a strong brand identity, your dark mode should reflect it. This recipe walks you through customizing:

  1. Your dark brand color (the accent in dark mode)
  2. Your dark page background (the main backdrop)
  3. Your dark elevated surface (cards, panels, widgets)
  4. Your dark mode logo (a light-colored version of your logo)
  5. Your color mode strategy (force dark / let visitors choose / match OS)

Each is independent - you can customize one or all four.

Decide your dark color strategy first

Pick one approach before diving into the colors:

Approach A - Invert your brand

Your light-mode brand is on a light background; your dark mode mirrors it on a dark background with the same accent color. Example: A coral brand on white in light mode, the same coral on near-black in dark mode.

When to use: when your brand color works on dark backgrounds (most coral / blue / teal / green accents do). Quick to set up.

Approach B - Shift the brand color

Your brand color in light mode is too dark / too saturated to read on dark backgrounds. Pick a lifted (lighter, brighter) version for dark mode. Example: A deep navy brand (#003049) on white in light mode becomes a lifted blue (#5aa3ae) on dark in dark mode.

When to use: when your light-mode brand color is too dark to read on dark backgrounds. Best results with high-saturation accents.

Approach C - Dark mode as a distinct sub-brand

Your dark mode is a deliberate, different visual identity - different accent, different surfaces. Example: A blue light-mode brand and a magenta dark-mode brand.

When to use: rare - usually for tech / gaming brands that have a separate "night mode" identity. Most sites benefit from approach A or B instead.

Pick A unless your brand specifically needs B or C. The instructions below assume A; B and C use the same steps with different hex values.

Step 1 - Pick your dark brand color (5 minutes)

The brand color drives buttons, links, accents, and the "primary" preset across the dark palette.

  1. Decide your dark brand hex. Two ways:

    From your existing brand color (approach A above):

    • Open your light-mode brand color in a hex picker (e.g. coolors.co)
    • Lift it 10-20% - increase the lightness, slightly decrease saturation. For example: #ee4036 → #ff5350.
    • Test it visually against a dark background to confirm it stays legible.

    From scratch (approach B):

  2. In WordPress, go to Appearance → Customize → Site Skin

  3. Scroll to find Theme Color (Dark Mode) - the field for dark_site_primary_color

  4. Paste your hex

  5. Click Publish

To preview the change:

  1. Set Color Mode (also in Site Skin) to Dark temporarily - see Step 5 for the permanent strategy
  2. Reload the site front-end
  3. Buttons, links, and accents should now use your new dark brand color

Step 2 - Pick your dark page background (5 minutes)

The page background is the main dark backdrop behind all content.

Common approaches:

  • Near-black (#0a0a0a to #121212) - modern, like Twitter / GitHub dark
  • Deep navy / blue-black (#1A1A2E, the default) - gentler than pure black, the BuddyX baseline
  • Charcoal / warm dark (#1c1c1f, slight warmth) - softer for long reading
  1. In Customize → Site Skin, find Body Background Color (Dark Mode) - the field for dark_body_background_color
  2. Paste your chosen hex
  3. Click Publish

Avoid:

  • Pure black (#000000) - too high contrast, hurts on OLED screens, looks unfinished
  • Anything below #0a0a0a lightness - same problem

Step 3 - Pick your dark elevated surface (5 minutes)

The "elevated surface" is cards, panels, widgets, and any UI that needs to feel slightly raised above the page background.

The elevated surface should be slightly lighter than the page background - usually by 8-15 lightness points. Example: page bg #0a0a0a → elevated #16213E or #1f1f1f.

  1. In Customize → Site Skin, find Box Background Color (Dark Mode) - the field for dark_box_background_color
  2. Paste your chosen hex
  3. Click Publish

If you want even more depth:

  • Secondary background (dark_secondary_background_color) - a subtle tint between page-bg and box-bg, for transitional surfaces
  • Content background (dark_content_background_color) - the main post / page content area

Most sites only need to customize the page-bg + box-bg pair. The rest can inherit from those two.

Step 4 - Upload a dark mode logo (5 minutes)

Your light-mode logo (designed to read on white) probably won't read well on dark backgrounds. Upload a light-colored version specifically for dark mode.

If you have a dark-mode logo file ready

  1. Go to Customize → Site Identity
  2. Find Dark Mode Logo - a second logo upload field next to your main logo
  3. Click Select Logo, upload your light-colored version
  4. Skip cropping
  5. Click Publish

The swap happens automatically the moment dark mode applies - no extra config needed.

If you don't have a dark-mode logo file yet

Two quick options:

  • Inverted version: open your logo file in any image editor, invert the colors, save as a separate file. Works for monochrome logos.
  • Light-color recolor: replace the dark color in your logo with a light color (white / off-white / your brand color lifted). Works for vector logos in Illustrator / Figma / Affinity.

If your logo is a wordmark only (no graphic), you might not need a separate dark logo at all - just rely on dark_site_title_color to render the wordmark in light text. Check your light-mode logo first.

Step 5 - Decide your color mode strategy

Pick one of two approaches in Customize → Site Skin → Color Mode:

Strategy What visitors see Best for
Light Light mode by default (dark palette applies only if a visitor toggles) Sites whose brand identity is light, or where dark mode is an opt-in extra
Dark Dark mode by default (light palette applies only if a visitor toggles) Tech / gaming sites that are dark-first, or sites where you want everyone in the customized dark identity

Then decide if visitors get a toggle to override the default:

  1. Customize → Site Skin → Color Mode → Show color-mode toggle: On = visitors get a sun/moon icon they can click to switch modes
  2. Toggle Position: Floating (side of screen) / Header / Mobile only / Both - pick whichever fits your header crowdedness

Most sites: Light + Show toggle on + Position: Floating - a predictable default with a way for visitors to override.

Step 6 - Verify dark mode looks right

  1. Set Color Mode to Dark temporarily (so you can see the dark version regardless of your OS preference)
  2. Reload the front-end of your site
  3. Check each surface:
    • Home page
    • A blog post
    • The header + menu (with hover states)
    • The footer (with widget content)
    • A button (your dark brand color should be the bg)
    • A link in body text (your dark brand color)
    • The site title in the header (should be readable)
  4. If your logo is now invisible, you skipped Step 4 - upload a dark logo
  5. If your brand color is hard to read on dark, lift it more (Step 1)
  6. If the elevated surfaces blend into the page background, increase the lightness difference between them (Step 3)

Once everything looks right, set Color Mode back to your chosen strategy (Light or Dark from Step 5).

Bonus - Verify contrast (WCAG AA)

Accessibility-conscious sites should verify text-on-background contrast meets WCAG AA (4.5:1 for body text, 3:1 for large text + UI elements).

For each text-on-background pair:

  1. Find the two hex values (e.g. text color and background color)
  2. Open webaim.org/resources/contrastchecker/
  3. Paste both hexes
  4. Verify the AA contrast ratio is met (it shows pass/fail)

Critical pairs to check:

  • Body text color (dark_body_text_color) on page background (dark_body_background_color)
  • Body text color on box background (dark_box_background_color)
  • Link color (dark_site_links_color) on body background
  • Button text (dark_site_buttons_text_color) on button background (dark_site_buttons_background_color)

If a pair fails, adjust the lighter of the two colors to be lighter, or the darker to be darker.

Common questions

My dark brand color works in body text but looks dim on buttons. Why? Buttons are filled surfaces (the brand color IS the background), so the brand color appears at 100% saturation. In body text, the same color appears as small letters against a dark background - it can look weaker. The fix: use the same dark brand color for buttons but lighten the link color separately (dark_site_links_color).

Can I have a different dark brand color from my light brand color? Yes - this is exactly what dark_site_primary_color is for. It defaults to a lifted version of your light brand color, but you can set it to anything. Approach C in the strategy section uses this.

What's the difference between "page background" and "box background"? Page background is the main backdrop behind everything. Box background is cards, widgets, panels - surfaces that should feel slightly raised. The two should differ by ~8-15 lightness points for visible depth.

Block-pattern landing pages still look light in dark mode. Why? This shouldn't happen on 5.1.0+ - the theme ships dark overrides for the WordPress block-library color presets (--wp--preset--color--base, --wp--preset--color--contrast, etc.). If your block pattern uses a different palette slug, see Dark Mode → Block patterns. For child-theme palette slugs, use the buddyxpro_dark_wp_preset_map filter - see Filters Index.

Can I have a separate dark logo for the header but use the main logo elsewhere? The Dark Mode Logo applies everywhere dark mode applies (header, header sticky variant, mobile menu). It doesn't have separate placements. If you need that, you'd need custom CSS.

Related

Got a question? We're a friendly team - drop us a line at support@wbcomdesigns.com.