Theming Engine & Color Modes
Relevant source files
The following files were used as context for generating this wiki page:
The theming engine manages the visual appearance of the application through a combination of color modes, theme colors, and font pairings. It controls global CSS variables to switch between light and dark modes, apply specific color palettes, and update typography across the site. The system relies on data attributes and class names applied to the <html> element to propagate styles.
Sources: src/utils/theme.ts, src/assets/styles/theme.css:33-36
Color Modes
Color modes control the "appearance" or luminosity of the UI. The system supports three primary modes: light, dark, and system. When set to system, the engine listens for changes in the browser's prefers-color-scheme media query to toggle the effective mode.
Appearance Management Flow
The selection process involves updating localStorage, calculating the effective mode, and updating the DOM by toggling a .dark class on the document root.
The application uses the following logic to determine and apply the mode:
- Storage: Persists the user choice in
localStorage. - System Preference: Uses
window.matchMedia('(prefers-color-scheme: dark)')to detect OS-level settings. - DOM Update: Adds the
.darkclass todocument.documentElementif the effective mode isdark.
Sources: src/components/Settings/ThemeMode/utils.ts:13-25, src/utils/theme.ts:25-32
Theme Colors
Theme colors define the primary and secondary color palettes. Unlike color modes which use classes, theme colors use the data-theme attribute on the <html> element. The engine supports several predefined palettes including blue, purple, yellow, emerald, and orange.
Supported Themes
| Theme ID | Primary Hue (OKLCH) | Complementary Secondary |
|---|---|---|
default | 106 (Greenish) | Orange-red |
blue | 240-280 | Orange |
purple | 290-320 | Yellow-green |
yellow | 80-105 | Purple |
emerald | 162-195 | Coral |
orange | 25-70 | Blue |
Sources: src/assets/styles/theme.css:45-125
Implementation Detail: Landscape Variables
Specific features, such as the landscape illustration, map their own internal variables to the primary color ramp of the selected theme.
--landscape-dark: Maps to--color-primary-800--landscape-front: Maps to--color-primary-500--landscape-sky: Maps to--color-primary-400
Sources: src/components/Settings/ThemeColor/theme-color.ts:7-14
Typography & Font Pairings
The theming engine extends to typography through a system of "pairings." A pairing defines the font families used for the body, headings, and navigation menus. These are applied via the data-font attribute.
Font Pairing Configurations
| ID | Label | Body Font | Heading Font |
|---|---|---|---|
work | Work | IBM Plex Sans | Space Grotesk |
play | Play | Nunito | Fredoka |
live | Live | Source Sans 3 | Lora |
Sources: src/components/Settings/Font/pairings.ts:70-98
CSS Variable Injection
The system generates CSS rules that map generic variables to pairing-specific fonts:
[data-font='work'] {
--default-font-family: var(--font-ibm-plex-sans);
--font-heading: var(--font-space-grotesk);
--font-ui: var(--font-ibm-plex-sans);
}
Sources: src/components/Settings/Font/pairings.ts:145-151
Global Theming Architecture
The engine coordinates multiple state changes. When a user changes a setting in the UI, the following sequence occurs:
Prose & Inversion
The application utilizes the Tailwind CSS Typography plugin. It defines specific variable overrides for the .prose class to ensure readability in both light and dark modes.
- Light Mode:
--tw-prose-bodyusesvar(--color-primary-700). - Dark Mode: Variables are inverted via the
@variant darkblock, where--tw-prose-bodymaps to--tw-prose-invert-body(var(--color-primary-200)).
Sources: src/assets/styles/typography.css:12-45
The Theming Engine provides a cohesive way to manage visual state across the project, ensuring that color palettes, luminosity, and typography remain synchronized based on user preference or system settings.