Theming & Dark Mode

This page explains how light and dark themes are supported using Tailwind’s class-based configuration. It covers theme switching logic, accessible implementation, and how consistent visual identity is preserved across modes.

Class-Based Strategy

The Tailwind configuration uses a darkMode value of 'class'. This allows manual toggling of themes using JavaScript without relying on system preferences.

darkMode: 'class',
theme: {
  extend: {
    colors: {
      surfaceLight: '#F8F9FA',
      surfaceDark: '#18181B',
      textLight: '#1F2937',
      textDark: '#F4F4F5'
    }
  }
}

Pages use utilities such as bg-surfaceLight dark:bg-surfaceDark to automatically switch styles based on the presence of the dark class on the root <html> element.

JavaScript Theme Toggle

A single JavaScript function toggles the theme and stores the user’s choice in localStorage. This preference is applied on the next visit using document.documentElement.classList.

function toggleTheme() {
  const html = document.documentElement;
  html.classList.toggle('dark');
  const isDark = html.classList.contains('dark');
  localStorage.setItem('theme', isDark ? 'dark' : 'light');
}

This strategy gives users full control while avoiding unnecessary re-renders or layout shifts.

Syntax Highlighting

Code elements across all pages are themed using custom utility classes. These apply consistent color to each semantic role in the block: keys, values, functions, and comments.

.text-code-key - Reserved keywords and properties

.text-code-value - String literals and values

.text-code-function - Function names and event handlers

.text-code-comment - Comments or inline hints

System Preference Detection

When a user has not selected a theme, the script checks for window.matchMedia and applies a default that matches the system’s prefers-color-scheme.

const prefersDark = window.matchMedia(
  '(prefers-color-scheme: dark)'
).matches;
if (!localStorage.getItem('theme')) {
  if (prefersDark) {
    document.documentElement.classList.add('dark');
  }
}

This helps first-time visitors experience the site in the mode that best aligns with their device and habits.