Universal Dark Mode | RSL Documentation

Quick Start

Universal Dark Mode automatically transforms any page to dark mode by analyzing computed colors and applying intelligent transformations.

Installation

Include the scripts in this order:

<!-- Required: Color manipulation utilities -->
<script src="javascript/color-adjuster.js"></script>

<!-- Required: Theme toggle functionality -->
<script src="javascript/theme-toggle.js"></script>

<!-- Universal Dark Mode -->
<script src="javascript/universal-dark-mode.js"></script>

Note: The script auto-initializes on page load. No additional setup required!

Features

Auto Detection

Uses HSP algorithm to detect light vs dark colors

Gradient Support

Transforms CSS gradients color by color

Semantic Colors

Preserves info, success, warning, error hues

Reversible

Restores original styles on theme switch

Dynamic Content

MutationObserver handles new elements

Exclusions

Skip elements with data-no-dark-mode

How It Works

Theme Change Detection — Listens for data-theme attribute changes on <html>
Element Scanning — When dark mode activates, scans all elements in the document
Color Analysis — Reads computed backgroundColor, backgroundImage, color, and borderColor
Light/Dark Detection — Uses the HSP algorithm to determine if a color is light or dark
Hue Preservation — Semantic colors (blue, green, orange, red) keep their hue but adjust lightness
Style Application — Applies inline style overrides dynamically
Restoration — Stores original styles and restores them when switching back

The HSP Algorithm

Human Sensitivity Poo (HSP) accounts for how humans perceive color brightness:

HSP = sqrt(0.299 * R² + 0.587 * G² + 0.114 * B²)

// If HSP > 127.5 → color is "light"
// If HSP ≤ 127.5 → color is "dark"

Excluding Elements

Add data-no-dark-mode to any element to exclude it (and its children) from transformation:

<div data-no-dark-mode>
    <!-- This stays as-is in dark mode -->
    <p style="background: yellow; color: black;">
        I won't be transformed!
    </p>
</div>

API Reference

Methods

Method	Description
`RSL.UniversalDarkMode.init()`	Initialize the module (called automatically)
`RSL.UniversalDarkMode.refresh()`	Force re-scan and re-transform all elements
`RSL.UniversalDarkMode.destroy()`	Remove all transformations and clean up
`RSL.UniversalDarkMode.setColors(obj)`	Customize the dark mode color palette
`RSL.UniversalDarkMode.getColors()`	Get the current color palette

Customizing Colors

RSL.UniversalDarkMode.setColors({
    bgDark: '#0d1117',           // GitHub-style dark
    bgDarkSecondary: '#161b22',
    textLight: '#c9d1d9',
    textLightSecondary: '#8b949e'
});

When to Use

Use Universal Dark Mode

Page builder generated content
Quick prototypes
Legacy pages without dark mode CSS
Dynamic/user-created content
Templates without custom theming

Use Custom CSS Instead

Brand-specific dark theme colors
Precise control over dark mode appearance
Complex custom components
Performance-critical pages
When you need CSS-only solution

Note: Universal Dark Mode applies inline styles, which have high specificity. For brand-specific themes, write custom [data-theme="dark"] CSS rules instead.

Resources

View Test Page Full Documentation Back to Layout & Utilities