Skip to main content

Implementing dark mode in BUX

Pierre Fortier

Now available in BUX 1.5, dark mode is built to be flexible, accessible, and easy to adopt. Get an overview of how it works and what developers need to implement it with confidence.

This blog is part of a two‑post series on dark mode in BUX, covering both the design and development sides of the work. While this post focuses on how to roll out dark mode on your own website, the companion design‑focused post dives into the design decisions behind dark mode.

Now available in BUX 1.5, dark mode provides developers with a fully supported theme that adapts across components while maintaining accessibility and brand consistency. This post focuses on how dark mode works in BUX and how to implement it.

We're excited to announce that dark mode is coming to BUX in version 1.5! This highly requested feature brings a modern, eye-friendly alternative appearance to Ohio State's design system while maintaining full accessibility and brand consistency.

What's new​

BUX 1.5 introduces a comprehensive dark theme that adapts all components automatically. The implementation is built on CSS custom properties (CSS variables), making it lightweight, performant and easy to integrate into your projects.

Key features​

Automatic theme switching​

BUX supports three modes: light, dark and auto (default)

  • Auto mode respects user's OS preference via prefers-color-scheme: dark
  • User preferences saved in localStorage
  • No flash of unstyled content (FOUC) on page load

Complete component coverage​

All BUX components have been updated to support dark mode, including:

  • Buttons, forms and interactive elements
  • Cards, heroes and content blocks
  • Navigation (menu, header, footer)
  • Tables, alerts and utilities
  • Typography and links

JavaScript API​

If you need to control the theme programmatically, BUX provides a simple JavaScript API:

// Set theme
window.BUX.theme.set('dark');   // Force dark mode
window.BUX.theme.set('light');  // Force light mode
window.BUX.theme.set('auto');   // Follow OS preference

// Get current theme preference
const currentTheme = window.BUX.theme.get(); // Returns 'dark', 'light', or 'auto'

// Check if dark mode is active
const isDark = window.BUX.theme.isDark(); // Returns true/false

Custom events​

BUX also emits a custom event whenever the theme changes, so your scripts can respond as needed:

document.addEventListener('bux-theme-change', (event) => {
  console.log('Theme mode:', event.detail.mode);     // 'dark', 'light', or 'auto'
  console.log('Is dark:', event.detail.isDark);      // true or false
});

What developers need to know​

Updating to 1.5​

If you're using a BUX component as-is, dark mode will "just work" when you update to BUX 1.5. No code changes are required.

However, if you've written custom CSS or extended BUX components, review the following to ensure everything adapts correctly.

1. Replace hardcoded colors with CSS custom properties​

Hardcoded color values won't adapt to dark mode. Instead, use BUX's CSS custom properties (tokens), which automatically respond to the active theme.

Old approach (won't adapt to dark mode):

.my-component {
  background-color: #fff;
  color: #212325;
  border: 1px solid #dfe3e5;
}

New, recommended approach (adapts automatically to dark mode):

.my-component {
  background-color: var(--white);
  color: var(--body-copy);
  border: 1px solid var(--gray-light-60);
}

2. Available CSS custom properties​

All BUX color tokens are now available as CSS custom properties, so you can safely rely on theme in both new and existing code.

3. Dark mode-specific overrides (when needed)​

In some cases, you may need styles to behave differently in dark mode. For those situations, use the dark-theme mixin:

.my-component {
  background-color: var(--white);
  border: 2px solid var(--gray-light-60);

  @include dark-theme {
    border-width: 4px; // Increase border width in dark mode
  }
}

The mixin generates: html.bux-dark-theme .my-component { ... }

4. Testing your implementation​

To ensure your site works as expected in dark mode:

1. Test with browser DevTools:

// In browser console
window.BUX.theme.set('dark');

2. Test auto mode:

  • Open Chrome DevTools → ⋮ menu → More tools → Rendering
  • Set Emulate CSS media feature prefers-color-scheme to dark
  • Verify auto mode respects this setting

3. Test all interactive states: hover, focus, active, visited

4. Check custom components for hardcoded colors

5. Review images and logos that might need dark-friendly versions

Best practices​

  • Always use CSS custom properties for colors in new code
  • Test in both light and dark themes during development
  • Don't assume white backgrounds – use var(--white) even when it seems redundant
  • Watch contrast closely; what works in light mode may not work in dark mode

Breaking changes?​

None! Dark mode is opt-in. Existing sites will continue to display in light mode unless:

  • Users with OS dark mode preference visit (if you implement the default auto mode)
  • You add a theme toggle to your interface
  • JavaScript explicitly calls window.BUX.theme.set('dark')

Questions?​

Reach out to the BUX team or open an issue in the repository. We're here to help make your transition to dark mode smooth and seamless!

For more details​

If you're interested in the "why" behind our color choices and how they align with Ohio State's brand, you can find that guidance in the Color section of the Brand Center. If you're looking for more hands‑on, technical guidance, including best practices and implementation details, head to the Dark Mode page on the BUX website. And if you have more specific questions, feel free to reach out to us at bux@osu.edu.

Back to top