Color Scheme Manager for Imba

A lightweight and straightforward Imba module for managing dark, light, and system color modes in web applications.

It enables you to easily get or set the user's preferred theme and ensures consistency with the browser or OS-level theme preferences.

🌗 Features

• Get and set color mode (light, dark, or system)
• Persists mode choice using imba.locals

🛠 Installation

Add the module to your Imba project. You can copy the code or include it as a component depending on your setup.

npm install imba-color-scheme

📦 Usage

import ColorScheme from 'imba-color-scheme'

const colors = new ColorScheme!

# Get the current actual color scheme
console.log colors.mode  # 'light', 'dark'
console.log colors.preset  # 'light', 'dark', 'system'

# The main differentce between .mode and .preset
# is that .mode can return only two options: dark or light
# while .preset could return three: dark, light or system

# There are also direct getters.
# Note that for example .dark will return true
# only if the scheme is explicitly set to dark
# this way only one of three getters will result in true
# which is convinient for using in an interface mode switcher
console.log colors.dark  # true or false
console.log colors.light  # true or false
console.log colors.auto  # true or false

# Set a specific color scheme
colors.mode = 'dark'
# or
colors.dark = true
# or
colors.preset = 'dark'

# Revert to system preference
colors.mode = 'system'
# or 
colors.auto = true
# or 
colors.preset = 'system'

# Check resolved system preference directly
console.log colors.system  # 'light' or 'dark' based on user's device setting

# set css properties for dark and light theme simultaniously
tag App
    <self> 'Hello world!'
        css bgc: light-dark(white, black) c: light-dark(black, white)

# or use double themed setting in css variables
css
    body
        $container: light-dark(white, black)

🧠 How It Works

• ColorScheme.mode returns 'dark' or 'light' taking into account saved preferencies or OS mode.
• ColorScheme.mode = value sets the mode and updates the document’s colorScheme.
• Also supports direct boolean getters and setters: ColorScheme.dark and ColorScheme.light.
• ColorScheme.system reads the user's system preference using window.matchMedia.

🎨 Managing light and dark shades

ColorTheme also contains a function shades(name, light, dark, steps), which
creates a banch of CSS variables (name0, name1, name2...) containing different shades for light (lightness decreases with each step) and dark (lightness increases with each step) themes.

The main idea is to define own colors in a canonical way: $name0, $name1 and so on, but SIMULTANIOUSLY for dark and light mode with the SAME name through applying the same lightness distance for provided defaults.

Example:

import ColorScheme from 'imba-color-scheme'

const cs = new ColorScheme!

cs.shades('base', {h:233, s:14, l:95}, {h:233, s:14, l:5}, [1,2,3,4,5,6])

# Function creates $base0 with provided values for light and dark themes, 
# and $base1, $base2 and so on, adding or subtracting the percent 
# to lightness defined in the last parameter (array).
# If no steps is defined the default array is used: [1,2,5,9,14,20,27,35,43]

tag Panel
    <self [bgc:$base3]> # hsl(233,14,92) - light mode, hsl(233,14,8) - dark mode

You only need to define, two-three main colors this way, since it is not common to use more colors in web design. As a result you will get all the needed shades in you CSS for light and dark themes automatically.

Note: There is also ColorTheme.css-var(name, value) helping function. It just creates a css variable in the root with a given value. Do not need leading dashes (--) in the variable name.