Crate makeover 

Shared theme loading + intent resolution for TOML-based theme files.

Used by GoingsOn, Balanced Breakfast (Tauri apps), audiofiles (egui), and the MNW web server. Themes are authored by intent (“human design”): colors are declared by role (surface / content / action / status / line / category), not by hue. This crate is the single place that resolves an authored theme into a full set of intent tokens — including the derived interactive states (hover/active/selection/row-stripe/contrast) that each app used to recompute itself — and emits them as CSS variables or RGB tuples.

Theme file shape:

[meta]
name = "Nord"
variant = "dark"          # or "light"

[surface]                 # container backgrounds by role/elevation
page = "#2e3440"; raised = "#3b4252"; sunken = "#434c5e"; overlay = "#3b4252"

[content]                 # text/ink by emphasis
primary = "#d8dee9"; secondary = "#e5e9f0"; muted = "#616e88"

[action]                  # interactive / brand color
primary = "#81a1c1"

[status]                  # state semantics
danger = "#bf616a"; success = "#a3be8c"; warning = "#ebcb8b"; info = "#88c0d0"

[line]
border = "#4c566a"

[category]                # distinct decorative colors for tags/badges/charts
one = "#bf616a"; two = "#a3be8c"; three = "#81a1c1"
four = "#ebcb8b"; five = "#b48ead"; six = "#88c0d0"

Structs

Oklab

A color in OKLab (perceptually uniform): l lightness in [0,1], a/b opponent axes.

Rgb

An sRGB color. Hex round-trips losslessly.

SemanticTokens

A fully resolved intent layer: every token key → concrete #rrggbb. Includes both authored base intents and the computed derived intents.

ThemeColors

A loaded theme: metadata plus the authored colors, flattened to dotted keys (e.g. "surface.page", "status.danger", "category.one").

ThemeMeta

Theme metadata parsed from the [meta] section.

ThemePreview

A four-color preview for theme thumbnails: the representative swatch from each of the principal roles.

Constants

BASE_INTENTS

Authored base intents: (TOML dotted source key, canonical token key). These are read straight from the theme; the token key is the CSS-var stem (--{token}) and the rgb() lookup key.

COLOR_SECTIONS

The color sections an authored theme may declare.

Functions

bundled_themes_dir

The theme directory this crate ships, for use as a build-from-source fallback.

darken

Shift OKLab lightness down by delta (perceptually uniform).

delete_theme

Delete a custom theme by ID.

export_theme

Export a theme to a user-chosen path.

extract_colors

Extract the intent color sections into a flat HashMap with dotted keys like "surface.page", "status.danger", "category.one".

find_theme_path

Find a theme file by ID in the given directories.

import_theme

Import a theme TOML file into the custom themes directory.

intent_css_declarations

Emit the resolved intent layer as CSS declarations (no selector), one --token: #hex; line each, in deterministic (BTreeMap) order.

intent_css_vars

Emit the resolved intent layer as a :root { … } block — the single TOML → CSS mapping every web surface injects.

lighten

Shift OKLab lightness by delta (perceptually uniform). Positive lightens.

list_themes_from_dirs

Scan directories for .toml theme files and return metadata for each.

load_semantic

Load a theme and resolve it to the full intent token set in one step.

load_theme

Load a complete theme (metadata + colors) by ID from the given directories.

load_theme_preview

Load just the preview swatches for a theme — for UI thumbnails.

mix

Interpolate between a and b by t in [0,1] in OKLab (perceptual blend).

parse_meta

Parse the [meta] section into ThemeMeta.

parse_theme_str

Parse a complete theme (metadata + colors) from raw TOML content, with no filesystem access. For callers that embed themes at compile time.

readable_on

Pick black or white for legible text on bg, by the higher WCAG contrast ratio (so the choice meets AA wherever the background allows it).

resolve

Resolve an authored theme into the full intent token set.

validate_theme_id

Validate a theme ID contains only safe characters (alphanumeric, hyphens, underscores).

wcag_contrast

WCAG 2.x contrast ratio between two colors, in [1, 21].