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/row tones/contrast), and emits them as CSS variables or RGB tuples. No app recomputes them itself.

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"

Modules§

ratio: The look ratios the derivations use, one place.

Structs§

ColourLiteral: A colour written as a literal: the line it is on, counted from 1, and the declaration that holds it.
FontFace: One @font-face an override brings with it.
FontOverride: One product’s answer for one slot: the stack, and any faces it ships.
Listed: What a scan of the theme directories found.
LookContext: What the sheets a page links define, which Rule::TokenShadow and Rule::UndefinedVar read against.
LookFinding: A look written by hand: the rule, the line it is on counted from 1, and the declaration that holds it.
LookReport: What a check of a tree found.
LookTree: A repo’s web files, read by exclusion.
LookTreeFileError: look-tree.toml could not be read as a tree’s description.
Oklab: A color in OKLab (perceptually uniform): l lightness in [0,1], a/b opponent axes.
Rgb: An sRGB color. Hex round-trips losslessly.
Rgba: An sRGB colour with an alpha, which is what a resolved intent is.
SemanticTokens: A fully resolved intent layer: every token present, as a colour. 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: The search path load_theme and list_themes_from_dirs take.
ThemeId: A theme’s id: the stem of its file, and the value a picker stores.
ThemeMeta: Theme metadata parsed from the [meta] section.
ThemeOption: One theme, as a picker offers it.
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.
UnmetFloor: A floor resolve could not clear, with how far it got.

Enums§

ContrastTier: How legible a theme’s muted text is, measured rather than declared.
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.
LoadError: Why a theme could not be named, found, read or imported.
LookRule: One way of writing a look by hand.
LookTreeError: Why a tree could not be checked.
ThemeSelection: What the user chose, as opposed to what is being rendered.
Token: One resolved intent, by name.
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: the TOML dotted source key each is read from, and its token.
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.
GRAY_RAMP_LEN: How many steps the gray ramp has.
GRAY_RAMP_START: Where the gray ramp starts in ANSI_256, and how many steps it has.
HOUSE_MONO_FAMILY: The family name inside FONT_MONO, on its own, for a consumer that needs the name rather than the stack. A test asserts the two agree.
HOUSE_SANS_FAMILY: The family name inside FONT_SANS. See HOUSE_MONO_FAMILY.
HOUSE_WEIGHT_RANGE: The weight range both house faces carry.
LOOK_CEILINGS_FILE: The file at a tree’s root holding each rule’s ceiling.
LOOK_EXEMPT_FILE: The file at a tree’s root listing what the gate does not read, one path per line followed by the reason.
LOOK_TREE_FILE: The file at a tree’s root describing it to Tree::load.
STEP_FLOOR: The contrast a tonal step must clear against the token it is a step of.
THEME_ATTRIBUTE: The root attribute all_themes_css keys its blocks on.
TYPE_ROLES: The type roles beside the faces, each named by its job and emitted with them: the one strong weight, running text’s leading, and the leading of a line that is not running text (a title, a label, a single-line control).
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§

all_themes_css: Every theme in dirs as one stylesheet: an ambient-following default, then a keyed block per theme.
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.
colour_literals: Every declaration in css whose value writes a colour: a hex colour, a colour function (rgb(), oklch() and the rest), or a named colour in a property that takes one.
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 on the search path.
font_face_css: The @font-face rules for both slots, fetching from base_url.
gray_ramp: The gray ramp (indices 232-255) redrawn on a theme’s own lightness axis.
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: value; line each, in stem order. The only place a token becomes CSS text.
intent_css_vars: Emit the resolved intent layer as a :root { … } block — the single TOML → CSS mapping every web surface injects.
keyed_intent_css_vars: Emit one theme’s intent layer keyed by THEME_ATTRIBUTE, as :root[data-theme="<id>"] { … }.
lighten: Shift OKLab lightness by delta (perceptually uniform). Positive lightens.
list_themes_from_dirs: Scan the search path for .toml theme files.
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.
look_css: Every declaration in css that writes a look by hand.
look_markup: Every place html writes a look into the markup: a style attribute that sets more than custom properties, a <style> block, an SVG paint of its own.
look_script: Every place js (a script or a TypeScript module) writes an element’s look: an assignment to .style.<property>, style.cssText, setAttribute of style, or a string of markup that carries a style attribute.
mix: Interpolate between a and b by t in [0,1] in OKLab (perceptual blend).
order_theme_options: Put an already-collected set into the order a picker offers them in.
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.
quantize_legible: Index of the entry in palette closest to fg that clears floor against every one of grounds.
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.
theme_options: Every installed theme, in the order a picker should offer them.
tonal: A tonal step of base, ratio of the way toward the ground it is read against.
typography_css_declarations: The house font tokens and TYPE_ROLES 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.
wcag_contrast: WCAG 2.x contrast ratio between two colors, in [1, 21].

Crate makeover

Crate makeover Copy item path

Modules§

Structs§

Enums§

Constants§

Functions§

Crate makeover