← Back to Documentation

Theming System

The Quantum Design System provides a comprehensive theming system that allows applications to support light and dark themes with minimal effort. The system is built on CSS variables and can be extended for custom themes.

Key Features

CSS Variables

The theming system uses CSS variables (custom properties) to define theme values. These are organized into logical groups:

/* Brand colors - don't change with theme */
:root {
  --brand-dark-blue: #3E495B;
  --brand-middle-blue: #445E89;
  --brand-green: #00BE34;
  /* ... */
  
  /* Theme variables */
  --theme-background-primary: #FFFFFF;
  --theme-text-primary: #333333;
  /* ... */
}

Dark theme variables are defined using the [data-theme="dark"] selector and applied to the HTML element:

[data-theme="dark"] {
  --theme-background-primary: #222B45;
  --theme-text-primary: #FFFFFF;
  /* ... */
}

This approach allows for seamless theme switching without changing class names or reloading the page.

Theme Colors

The theming system provides a set of semantic color variables that adapt to the current theme:

Background Colors

Background Primary

var(--theme-background-primary)

Main background color

Background Secondary

var(--theme-background-secondary)

Secondary background color

Background Tertiary

var(--theme-background-tertiary)

Tertiary background color

Text Colors

Text Primary

var(--theme-text-primary)

Main text color

Text Secondary

var(--theme-text-secondary)

Secondary text color

Text Tertiary

var(--theme-text-tertiary)

Tertiary text color

Accent Colors

Accent Primary

var(--theme-accent-primary)

Main accent color

Accent Secondary

var(--theme-accent-secondary)

Secondary accent color

State Colors

Success

var(--theme-success)

Success state color

Warning

var(--theme-warning)

Warning state color

Error

var(--theme-error)

Error state color

Info

var(--theme-info)

Info state color

Using Themes in Components

To make your components theme-aware, simply use the theme variables in your CSS:

/* Example component CSS */
.my-component {
  background-color: var(--theme-background-primary);
  color: var(--theme-text-primary);
  border: 1px solid var(--theme-border-primary);
}

.my-component button {
  background-color: var(--theme-accent-primary);
  color: white;
}

.my-component button:hover {
  background-color: var(--theme-accent-secondary);
}

Components will automatically adapt to theme changes without any additional JavaScript logic.

For Web Components

In web components with Shadow DOM, import the base CSS and use the variables in your shadow root:

// Make sure the base CSS is loaded
loadBaseCSS();

// In your render method
render() {
  this.shadowRoot.innerHTML = `
    <style>
      :host {
        display: block;
        background-color: var(--theme-background-primary);
        color: var(--theme-text-primary);
      }
      
      button {
        background-color: var(--theme-accent-primary);
        color: white;
      }
    </style>
    
    <div>
      <button>Click me</button>
    </div>
  `;
}

JavaScript API

The theme system includes a JavaScript API for programmatic control:

import themeManager from '/assets/components/shared/theme-manager.js';

// Get current theme
const isDark = themeManager.isDarkTheme();
const currentTheme = themeManager.getTheme(); // 'light' or 'dark'

// Check if auto theme is enabled
const isAutoTheme = themeManager.isAutoTheme();

// Set theme explicitly
themeManager.setTheme('dark'); // or 'light'

// Toggle between light and dark
const newTheme = themeManager.toggleTheme();

// Enable automatic theme based on system preference
themeManager.enableAutoTheme();

Event Listening

You can listen for theme change events:

// Listen for theme changes
document.addEventListener('qds-theme-change', (event) => {
  const { theme, dark } = event.detail;
  
  console.log(`Theme changed to: ${theme}`);
  console.log(`Dark mode: ${dark}`);
});

Theme Switch Component

The <qds-theme-switch> component provides a user interface for changing themes:

Installation

Include the component in your HTML:

<script type="module" src="/assets/components/theme-switch/qds-theme-switch.js"></script>

<qds-theme-switch></qds-theme-switch>

Attributes

Attribute Type Description
dark Boolean Whether the current theme is dark
auto Boolean Whether to use system preferences

Events

Event Detail Description
theme-change { dark: boolean, theme: string } Fired when the theme is changed

Customization

You can customize the theme variables to match your application's branding:

/* Custom theme with different accent colors */
:root {
  /* Override default light theme */
  --theme-accent-primary: #7850C3;
  --theme-accent-secondary: #583C8C;
}

[data-theme="dark"] {
  /* Override default dark theme */
  --theme-accent-primary: #A78CDF;
  --theme-accent-secondary: #8970B5;
}

Creating Additional Themes

You can create additional themes by defining new selectors and changing the data-theme attribute:

/* High contrast theme */
[data-theme="high-contrast"] {
  --theme-background-primary: #000000;
  --theme-text-primary: #FFFFFF;
  --theme-accent-primary: #FFFF00;
  /* ... */
}

// Apply the theme
document.documentElement.setAttribute('data-theme', 'high-contrast');

Quantum Design System Theming v1.0.0