Theme Switching

Our theme system, which components depend on and is adapted on top of MkDocs Material style, supports both light and dark themes. All components automatically adapt to the selected theme using CSS variables.

CSS Variables

Our theming system is built on CSS custom properties (variables) that automatically update when switching themes.

Core Variables

:root {
  /* Background colors */
  --md-default-bg-color: #ffffff; /* Background color */
  --md-default-fg-color: #000000; /* Foreground/text color */

  /* Accent colors */
  --md-primary-fg-color: #1976d2; /* Primary accent color */
  --md-accent-fg-color: #ff6b35; /* Secondary accent color */

  /* Custom variables */
  --phantom-bg-secondary: #f5f5f5; /* Secondary background */
  --phantom-border: #e0e0e0; /* Border color */
  --phantom-accent: #1976d2; /* Accent color */
  --phantom-text-secondary: #666666; /* Secondary text color */
}

Visual Examples

Default Background
--md-default-bg-color

Secondary Background
--phantom-bg-secondary

Primary Color
--md-primary-fg-color

Accent Color
--phantom-accent

Theme-Aware Components

All our custom components automatically adapt to the current theme:

Light Mode Example

✓

Light Mode

How It Works

1. Base Variables: MkDocs Material provides base theme variables
2. Custom Variables: We extend these with our own --phantom-* variables, adapting our own styling approach
3. Automatic Switching: Variables update when theme changes

Try switching between light and dark mode using the theme toggle in the header to see how all components adapt!

Color Palette

Primary Colors

Primary
--md-primary-fg-color

Accent
--md-accent-fg-color

Phantom Accent
--phantom-accent

Status Colors

Success
#22c55e

Warning
#f59e0b

Error
#ef4444

Info
#3b82f6

Creating Theme-Aware Components

Example: Custom Card

.custom-card {
  background: var(--phantom-bg-secondary);
  border: 1px solid var(--phantom-border);
  color: var(--md-default-fg-color);
  padding: 1rem;
  border-radius: 8px;
}

.custom-card:hover {
  border-color: var(--phantom-accent);
}

This card automatically adapts to the current theme using CSS variables.

Dark Mode Considerations

When designing for both themes, consider:

1. Contrast Ratios: Ensure text remains readable in both modes
2. Color Meanings: Status colors should be distinguishable in both themes
3. Shadows: Use box-shadow sparingly as it may not work well in dark mode
4. Images: Consider providing theme-specific images when necessary

Testing Your Theme

Contrast Checker

Default Text on Default Background
This text should be clearly readable in both light and dark modes.

Secondary Text on Secondary Background
This combination is used for less prominent content.

Theme Toggle Location

The theme toggle button is located in the header navigation bar. Look for the sun/moon icon to switch between light and dark modes.

Best Practices

1. Use CSS Variables: Always use theme variables instead of hard-coded colors
2. Test Both Modes: Check your content in both light and dark themes
3. Semantic Colors: Use meaningful variable names that describe purpose, not appearance
4. Fallback Values: Provide fallback colors for older browsers if needed
5. Media Queries: Respect user's system theme preference with prefers-color-scheme