Beyond Inversion: Engineering a Contextual Dark Mode with SCSS Hooks and Triggers | Blog

When I first toggled the dark mode switch on my local engineering lab for ReadBoot, the result was, frankly, horrible [Image 1]. A naive mathematical inversion of hex codes had turned our “Futurist Carton” aesthetic into a high-contrast nightmare: white text was glowing (halation) against a pure black void, and our signature brand Crimson was vibrating so hard it was physically uncomfortable to read.

As a React developer, I had to make a choice: follow the path of least resistance with global CSS variables or architect a system that prioritized accessibility and brand integrity. Here is why I chose the latter.

The Common Path: Global CSS Variables

The most frequent implementation of dark mode today involves native CSS variables (Custom Properties) defined at the :root.

CSS

:root { --bg: #ffffff; --text: #000000; }
[data-theme='dark'] { --bg: #000000; --text: #ffffff; }

body { background: var(--bg); color: var(--text); }

Benefits

Performance: Theme switching is instant and happens at the browser runtime without a page reload.
Simplicity: It’s easy to understand and requires minimal code to get a “working” result.

Drawbacks

The “One-Size-Fits-All” Trap: It assumes every instance of a color should change the same way.
Limited Color Math: Native CSS variables cannot easily use Sass functions like color.adjust or rgba() at compile-time to desaturate brand accents specifically for dark backgrounds.
Halation Issues: Simply flipping #000 and #FFF creates a contrast ratio of 21:1, which causes visual fatigue and “light bleed” for users with astigmatism or photophobia.

My Choice: The “Hooks and Triggers” Methodology

I moved away from global overrides and toward a Contextual Hook pattern using SCSS mixins. In this architecture, a “Trigger” is a global state (like a [data-theme='dark'] attribute on the <html> tag), and a “Hook” is a localized SCSS mixin that tells a component exactly how to behave when that trigger is active.

The “.water” vs. “.star” Philosophy

The core of my decision-making was based on selective theme-awareness:

Water Elements (.water): These are fluid. Like water, they adapt to their container. Backgrounds and standard body text fall into this category—they shift roles seamlessly between “Paper” and “Ink”.
Star Elements (.star): These are constant. Like stars, they remain fixed points of reference regardless of the environment. Our primary logo and high-intensity brand marks must ignore the theme switch to maintain brand recognition.

Implementation: The `set-color-scheme` Mixin

By utilizing a three-tier design token system (Primitives → Theme Maps → Semantic Pairings), I built a mixin that retrieves the right color based on the current context.

SCSS

@mixin set-color-scheme($scheme, $theme: "light") {
  $current-theme: map.get($vars.themes, $theme);
  $pairing: map.get($vars.color-pairings, $scheme);
  
  background-color: map.get($current-theme, map.get($pairing, "bg"));
  color: map.get($current-theme, map.get($pairing, "text"));
  border-color: map.get($current-theme, "border");
}

Why This Matters for Accessibility

Accessibility is not a “nice-to-have”; it is a non-negotiable requirement. In dark mode, vibrant colors “burn” on dark backgrounds. To solve this, my system programmatically adjusts every brand color for the dark theme map :

Desaturation: For Scrambled Sounds, the “Dorsal Green” (#4F7353) is lightened by 10% and desaturated by 15% in dark mode to create a “Forest at Dusk” calm design.
Lightness Adjustment: Our primary Crimson (#DC143C) text on Charcoal results in a failing 1.08:1 contrast ratio. By hooking into the dark mode trigger, the mixin swaps this for a desaturated tint (#F05A7E) that meets the WCAG AA 4.5:1 ratio.
Elevation via Luminosity: Shadows are invisible in dark mode. Instead of using box-shadow, my system uses Surface Elevation—lightening the charcoal background slightly (e.g., from 0dp to 4dp) as an element moves closer to the user.

Professional Decision-Making in React

As a React developer, my role is to bridge the gap between design intent and technical performance. In layout.tsx, I implemented a THEME_INIT_SCRIPT that prevents the “Flash of Unstyled Content” (FOUC) by checking localStorage and system preferences before the first paint.

By choosing the Hooks and Triggers method, I’ve built more than just a “dark mode”; I’ve engineered a scalable, neuro-inclusive design system that respects the physiological needs of the user while protecting the visual authority of the brand.

Tech Stack Used:

React 18 for component architecture.
Sass (Dart Sass 2+) for complex color math and mixin logic.
TypeScript for enforcing token safety [Image 3].
Storybook for auditing semantic color pairings.