Dark Mode

Maple provides a unique Hybrid Dark Mode Architecture that automatically supports both system preferences and manual toggles without writing extra CSS.

How It Works

When you use the @dark: or @light: prefix, Maple generates two CSS rules for each utility:

System Preference Rule: Targets the standard @media (prefers-color-scheme) query. This works out of the box because it leverages the browser's native ability to detect and react to the user's operating system theme settings.
Manual Override Rule: Targets .dark or .light classes. Adding these classes to <html> element will override the system preference rule.


<!-- Text is black normally, white in dark mode -->
<div class="c-black @dark:c-white">
  Hybrid dark mode support
</div>

<!-- Complex nested queries -->
<div class="@dark:@md:bgc-gray-900">
  Dark mode gray background on medium screens
</div>

Manual Controls

You can force the application into a specific mode by adding classes to the <html> element. This is useful for theme switchers.

System Mode (Default): No class on <html>. Follows the OS setting.
Force Dark: <html class="dark">. Ignores system preference.
Force Light: <html class="light">. Ignores system preference.

Hybrid Mode

This hybrid behavior ensures that your site looks great out of the box based on user system settings, while still giving you full control to implement a manual toggle.

Disabling Hybrid Mode

If you prefer to handle dark mode entirely via media queries or entirely via classes, you can disable the hybrid behavior in the script configuration.


<!-- Disable hybrid behavior in the script tag -->
<script src="maple.js?nohybrid"></script>

With nohybrid, the @dark: prefix will only generate the @media (prefers-color-scheme: dark) rule.

Dark Mode Tuning

In dark mode, you can use Maple's color manipulation variables to systematically adjust your entire palette. You can change properties like lightness scale (--l-scale), chroma scale (--c-scale), hue rotation (--h-rotate) or lightness shift (--l-shift) globally or for specific sections.

Setting --l-shift to a negative value in dark mode is a powerful way to maintain visual hierarchy. It makes lighter tones (e.g., 200) become darker and darker tones (e.g., 800) become lighter, effectively flipping the shades. For example, this documentation site uses --l-shift: -0.7 in dark mode, and it's the only variable we set to achieve the desired look.

Here is a practical example of how you can use this technique:

Adaptive

⍟

Easy Dark Mode Automatic shade flipping

This component demonstrates how a single --l-shift variable can transform your entire interface for dark mode while maintaining perfect visual balance and contrast.

Dynamic Palette


<div
  class="
    --body=oklch(0.56_0.05_260)
    --primary=oklch(0.63_0.2_150)
    @dark:--l-shift=-0.7
    bgc-body-100/40
    brc-body-200/50
  "
>
  <div class="bgc-primary-100 c-primary-700 brc-primary-200">
    Adaptive
  </div>

  <div>
    <div class="bgc-primary c-white">⍟</div>
    <div>
      <strong class="c-body-900">Easy Dark Mode</strong>
      <span class="c-body-500">Automatic shade flipping</span>
    </div>
  </div>

  <div class="c-body-600">
    This component demonstrates how a single
    <code class="c-primary-700">--l-shift</code>
    variable can transform your entire interface for dark mode while
    maintaining perfect visual balance and contrast.
  </div>

  <div>
    <div class="bgc-primary-50"></div>
    <div class="bgc-primary-100"></div>
    <div class="bgc-primary-200"></div>
    <div class="bgc-primary-300"></div>
    <div class="bgc-primary-400"></div>
    <div class="bgc-primary-500"></div>
    <div class="bgc-primary-600"></div>
    <div class="bgc-primary-700"></div>
    <div class="bgc-primary-800"></div>
    <div class="bgc-primary-900"></div>
    <div class="bgc-primary-950"></div>
    <span class="c-body-400">Dynamic Palette</span>
  </div>
</div>

Deep Dive: Color Manipulation

Maple's color system is powered by OKLCH mathematics. For a deep dive into how colors resolve, fallback, and scale, check out the Color System page.