Crate makeover

Expand description

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]                 # the ink. Its emphasis steps are derived, not authored:
primary = "#d8dee9"       # `content-secondary` and `content-muted` are tonal
                          # steps of this toward `surface.page`. See `Emphasis`.

[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§

FontFace: One @font-face an override brings with it.
FontOverride: One product’s answer for one slot: the stack, and any faces it ships.
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").
ThemeDefaults: The themes an app falls back to, one per ambient mode.
ThemeDirs: Builds the search path load_theme and list_themes_from_dirs take.
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.
Typography: The whole typography layer for one product: the house defaults, plus whatever it overrides.

Enums§

Emphasis: How far a tonal step sits from the token it is a step of.
FontSlot: A slot in the house font vocabulary — the unit an override replaces.
ThemeSelection: What the user chose, as opposed to what is being rendered.
Variant: A theme’s kind, as declared by meta.variant.

Constants§

ANSI_16: The 16 colors an ANSI terminal addresses by index, in the PC/VGA arrangement the Linux console and most emulators start from.
ANSI_240: The fixed region of ANSI_256: the 6x6x6 cube and the gray ramp, without the sixteen repaintable system colors.
ANSI_256: The 256 colors an xterm-compatible terminal addresses by index, so that entry i is what the terminal paints for 38;5;i.
ANSI_240_OFFSET: What to add to an ANSI_240 index to get an ANSI_256 one.
BASE_INTENTS: Base intents: (TOML dotted source key, canonical token key). The token key is the CSS-var stem (--{token}) and the rgb() lookup key.
COLOR_SECTIONS: The color sections an authored theme may declare.
DISTINCT: The contrast ratio two colors must clear to read as separate areas.
FOLLOW: The spelling of “follow whatever the system is doing”, in every store.
FONT_MONO: The mono slot: code, data, identifiers, cell grids, anything monospaced.
FONT_SANS: The body / UI slot. Everything that is not the mono slot or brand tier.
WEBFONT_MONO_FILE: Filename a consumer writes the cut mono face to, under its own font URL.
WEBFONT_SANS_FILE: Filename a consumer writes the cut body face to. See WEBFONT_MONO_FILE.

Functions§

ansi_intent: The authored intent painting ANSI slot index under a theme of variant, as a dotted key into ThemeColors::colors.
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.
derive_tonal_steps: Fill in the tonal steps of content.primary, overwriting whatever the theme authored under those keys.
embedded_themes: The themes this crate ships, as (id, toml_source) pairs.
emphasized: A named tonal step of base against the ground it is read on.
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.
font_face_css: The @font-face rules for both slots, fetching from base_url.
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.
quantize: Index of the entry in palette that looks most like c.
quantize_against: Index of the entry in palette closest to fg that still reads against bg.
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.
tonal: A tonal step of base, ratio of the way toward the ground it is read against.
typography_css_declarations: The house font tokens as CSS declarations (no selector), for a caller that is composing its own block.
typography_css_vars: The house font tokens as a :root { … } block.
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].

Crate makeover

Crate makeover Copy item path

Structs§

Enums§

Constants§

Functions§

Crate makeover