Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Theming

Styling is Rust: semantic tokens plus mixing rules. Short token fields map onto Material Design 3 roles (Tokens::scheme() for the full set). See Material Design 3 foundations.

Aliases: canvas/surface/panel/text/muted/primary/ accent/danger/border/selection. Tokens::from_aliases builds a scheme from those fields. Colorways sync containers from those aliases and recompute solid-fill on_* roles for contrast. Washes use scheme state layers (hover_fill / pressed_fill). Desktop control corners are M3 shape None unless Tokens::with_shape selects Tight, Soft, Pill, or the Material component map (see foundations). Tabs, app bars, banners, and exclusive segments stay flush under every policy. Type size is the M3 scale times Tokens::font_scale (1.0 by default). Shadows follow Tokens::with_elevation. Constructors take Tokens. Tokens.density (Compact / Default / Comfortable) sets control pad (pad), inter-item gap (space), and container inset. A *Face enum on the same constructor picks the painted look (RowFace, CardFace, FieldFace, TreeFace). ControlSize Compact and Comfortable stay per-control overrides; Default follows window density.

Built-in names are 40 palettes: dark, light, high-contrast, and community colorways (Solarized, Gruvbox, Catppuccin, Nord, Tokyo Night, Dracula, Everforest, Kanagawa, Ayu, GitHub, and others). theme::named and theme::code_highlight pick UI tokens and the iced highlighter face together. Catalog paper, accents, and status stay hex. Body and mute ink are theme::auto_ink on the canvas (87% / 60%). A dumped terminal foreground is not body copy. high-contrast is defined in Rust. Register more on ThemeCatalog. Boot.theme is a concrete name and defaults to dark. Boot::transparent asks iced for an ARGB buffer. Boot::decorations sets the client title bar. light and dark are a neutral desktop pair. Persist defaults follow_os on, so host chrome layers onto that pair; pick another catalog name to choose a colorway. markdown_view paints inline code and links from Tokens::scheme() (on_surface, surface_container_high, primary). Truncation is slicing the source before MarkdownDoc::parse.

#![allow(unused)]
fn main() {
let mut cat = icedtea::theme::ThemeCatalog::new();
cat.register("brand", icedtea::theme::named("dark").tokens, true);
let tokens = cat.resolve("brand")
    .with_font_scale(1.125)
    .with_shape(icedtea::m3::ShapePolicy::Material);
let _ = tokens.primary;
}

Persist stores the same fields on UiState (density, font_scale, shape, elevation). Restore with ui.look(tokens). Boot has the same setters so a window starts on that look.

Chrome labels come from Catalog::for_locale. English, Vietnamese, Japanese, Chinese, Arabic, and Urdu are built in. Direction is direction_for on the locale (Arabic and Urdu are right-to-left). Tokens.direction flips pick-list chevrons, disclosure marks, tree twisties, search icons, button leading/trailing icons, list slots, and the scroll rail (end side). Menu and toolbar rows take that direction and call order.

Live switch: store a theme name on state and return icedtea::theme::iced_theme(&name, tokens) from the theme function.

Families are explicit pairs (github → github-dark / github-light, and the other real couples). A follow-OS preference selects the light or dark member of one family (default family: light / dark). High-contrast is its own name. Names without a pair do not follow the OS. Persist stores theme plus optional family and follow_os (follow_os defaults on). Mode changes come from iced (system::theme / theme_changes).

Follow-OS chrome

Persist defaults follow_os on. The desktop pair (light / dark) follows OS appearance; host colors layer on top. A named colorway is a choice: set theme to that name, and set follow_os to false to keep the palette as authored (or pass OsChrome::empty).

With follow_os true:

  1. Resolve the family light/dark member from OS appearance (as above).
  2. Read host chrome via theme::os_chrome (boot, main thread on macOS) or theme::listen_os_chrome (live updates when accent or color-scheme changes).
  3. Apply with theme::apply_os_chrome. Each Some field overwrites the matching token; the rest of the pair (or chosen colorway) stays. Selection is rebuilt from primary + canvas.

What the host fills (missing fields stay on the colorway):

TokenmacOSWindowsLinux (portal, Wayland or X11)
primarycontrol accentsystem accentportal accent when published
canvaswindow background (system gray, not paper white)COLOR_WINDOW—
surfacetext background (often white in light mode)button face—
panelcontrol backgroundbutton face—
textlabelwindow text—
mutedsecondary labelgray text—
borderseparatorbutton shadow—

Success, warning, and danger always stay on the colorway. Decorated windows keep the native title bar. Turn follow-OS off for high-contrast or a fixed brand palette.

#![allow(unused)]
fn main() {
use icedtea::theme::{self, OsChrome};

let base = theme::named("dark").tokens;
// Opt out: colorway only
let pure = theme::apply_os_chrome(base, false, OsChrome::empty());
assert_eq!(pure, base);

// Opt in: layer whatever the host reported
let live = theme::os_chrome();
let tok = theme::apply_os_chrome(base, true, live);
let _ = tok.canvas;
}