- framework-01-w2: repair 1 - framework-01-w2: RowStyle and ShapeTokens::rows go (size.rs, lib.rs rows of the sheet) - framework-01-w2: list rows: option rows rounded, others square; layer rules in every theme (show.rs row of the sheet) - framework-01-w2: review fixes (review-1) - framework-01-w2: review fixes (review-1, files the rulings name) - framework-01-w2: the escaped-sweep trial follows the sweep rule: only the eyes it switched are restored (fw01 round 2) - framework-01-w2: a drop past the last item in reading order lands at the end, in every layout (fwcw round 3)
18 KiB
Suite themes
A suite theme is a named set of seeds and pins from which every Craft app derives its colours, shape and size tokens, so one choice in one app can restyle the whole suite. This page is the reference for theme authors and for app developers adopting the suite theme.
| Crate | Contents |
|---|---|
craft-theme |
Token model, derivation, contrast rules, theme file format, built-ins, selection and its resolution. No egui, no I/O; builds for wasm. |
craft-theme-store |
The suite folder: user themes, selection.json, the lock/revision protocol and the change watcher. |
craft_ui::style |
The bridge to egui: UiTokens, StyleCx and the component styles that read them. |
Tokens
Tokens come in two layers. A theme file only states seeds and exceptions; everything else is derived.
- Primitives: colour, 12-step ramps, fixed scales (space, radius, stroke, opacity, duration, easing, elevation).
- Semantic tokens:
surface.*,text.*,line.*,state.*,accent.*, status, overlay, data and caption colours, plus shape, size, space, motion and type tokens.
There are no component tokens: every component computes its look from the semantic tokens, in its style in the UI library crates.
resolve(theme, appearance, app) builds the tokens for one appearance: mode (light, dark),
contrast (standard, high), size (compact, comfortable), text size (small, default, large and
larger) and reduced motion. Derivation order, later steps winning: seeds (the theme's, with the mode's overrides), then ramps, then the theme's pins, then
the app's pins (apps.<id>), then the theme's high-contrast pins, then the app's
(apps.<id>.high_contrast).
Theme file (craft-design-theme, version 1)
{
"schema": "craft-design-theme", "schema_version": 1,
"id": "user.navy", "name": "Navy", "version": 1,
"variants": "both",
"contrast_intent": "standard",
"seeds": { "neutral": "#535353", "accent": "#78ADF6",
"status": { "good": "#85DC6A", "warn": "#E8B046", "bad": "#FF8080", "info": "#78ADF6" } },
"shape": null,
"light": { "surface.panel": "#F0F0F0" },
"dark": { "surface.panel": "#535353" },
"high_contrast": { "light": {}, "dark": {} },
"apps": { "photocraft": { "light": {}, "dark": { "surface.canvas": "#282828" }, "high_contrast": {} } }
}
| Key | Required | Value |
|---|---|---|
schema, schema_version |
yes | "craft-design-theme", 1 |
id |
yes | [a-z0-9][a-z0-9._-]{1,63}; craft. is reserved for built-ins and refused in the library; Windows device names (con, nul, com1 ...) are refused as the first dot-separated part |
name |
no | display name; default the id |
version |
no | the author's revision, default 1 |
variants |
no | "both" (default), "light" or "dark" |
contrast_intent |
no | "standard" (default) or "low": the theme is meant to be soft, and pickers label it "Low contrast" |
seeds |
yes | neutral, accent and status.good/warn/bad/info, all required |
shape |
no | null, or { "radius": { control, popup, window, panel, button, pill? }, "radius_offset": { control?, popup?, window? }, "edge": "flat" or {"bevel": {"width": 1}}, "knob": "round" or "tab", "wells": "square" or "round" }; knob is the shape of a value track's thumb (default "round"; Classic's "tab" is an upright tab); wells is the shape of a colour well that stands on its own, SwatchPair's (default "square"; Adwaita, Breeze and Soft are "round"); a radius is a number or "full"; radius needs the first five keys when present and fixes the radii at every Size; radius_offset (numbers, negative allowed, missing keys 0) is added to the control, popup and window radii in force, so the theme keeps its own shape at every Size (Soft: control +1, popup +2, window +2, which makes 7/10/14 at Comfortable and 4/6/8 at Compact); a "full" radius and panel, button and pill are not offset, and a sum below 0 is 0; pill (switch, slider, progress and badge shapes, clamped to half the part's height) defaults to "full", and Classic sets it to 0 |
light, dark |
no | colour pins: dotted token path to #RRGGBB, #RRGGBBAA or a reference "{token.path}" (see References); surfaces (surface.* except surface.scrim) must be opaque. A seeds key holds that mode's seed overrides: neutral, accent and status.good/warn/bad/info, each optional; a field it names replaces the theme's seeds value in that mode and the rest fall through |
high_contrast |
no | { "light": {...}, "dark": {...} }, pins used only in high contrast; no seeds key (it is an error there and in apps) |
apps |
no | per-app { light, dark, high_contrast }, applied over the theme's values for that app; its high_contrast pins apply after the theme's |
- JSON, at most 256 KiB.
schema_versionis the format;versionis the author's revision. - Paths are flat dotted strings (
"surface.panel"), never nested objects. - References: a pin value
"{accent.solid}"takes the final value of that colour token (after derivation and the contrast pass) for the theme, mode, contrast and size being resolved, so it follows the accent when the theme's accent changes. A target the theme pins reads the pinned value, a reference may name another reference, and a derived target reads the value derived from the other references' final values (the theme resolves again with every reference applied until no reference's value changes). References that never settle, such as"state.selected": "{state.selected_hover}"where the hover state derives from the selected one, are an error naming the key. It works inlight,dark,high_contrastandappsmaps. A name that is no colour token, and a cycle of references, are errors naming the key and the reference. Only colour pins take references;seedsdo not. - A pin map or
seedsoverride for a mode the theme lacks is an error when it is not empty. - Two-variant themes whose modes need different seeds (Pro, Soft) put the differing fields in
light.seedsordark.seedsinstead of pinning the derived colours. writerefuses a theme that would not parse back (ThemeDef::validate: pins for a missing mode, overrides of the wrong kind, translucent surfaces, negative or non-finite lengths).- Unknown keys outside the pin maps are allowed and kept byte for byte when the store rewrites the file. An unknown path inside a pin map is an error.
- A newer
schema_versionis refused and the file left alone. A file with anotherschema(the earliercraft-themeformat) is skipped by the library and counted, not reported. craft-theme check <file>... [--json]reports every error with its path (dark."surface.panel": not a colour) and every contrast warning per appearance. Exit code 1 for errors, 0 otherwise.
Built-in themes
craft.artcraft, craft.graphite, craft.studio, craft.adwaita, craft.breeze, craft.pro,
craft.soft (both variants); craft.pro-light-gray, craft.classic (light only);
craft.solarized-dark (dark only). craft.soft has contrast_intent: low. craft.app-default is not a theme: it stands for the
app's own palette, and settings lists it beside the others. High contrast is a setting, not a
theme. SUITE_DEFAULT is craft.artcraft.
Contrast rules
Users must be able to tell text and state indicators apart; nothing else is a rule.
High contrast meets every minimum below: it moves pinned values that miss one. Standard contrast follows the theme's design: a pinned value never moves, and a pair it misses is reported as a warning (the warning = lines of the token dumps), not a failure. Colours a theme leaves unpinned are still derived to meet the Standard minimums.
| Pair | Standard | High |
|---|---|---|
text.normal, text.muted, text.faint on surfaces (background, panel, chrome, raised, sunken), state.hover and state.pressed |
4.5 | 7 |
text.on_selected on state.selected and state.selected_hover |
4.5 | 7 |
accent.text on surface.panel, surface.raised and surface.sunken; accent.on_soft on accent.soft |
4.5 | 7 |
Status text (status.good.fg ...) on surface.panel, surface.raised and its own status.*.bg |
4.5 | 7 |
text.on_accent on accent.solid, accent.hover and accent.pressed; text.on_strong on accent.strong, accent.strong_hover and accent.strong_pressed; text.on_status on the status solids and their hover and pressed steps |
4.5 | 7 |
line.focus on the surfaces; accent.solid on the control surfaces (panel, raised, sunken: checked and selected marks); line.mark (slider marks and ticks, the badge ring) on the control surfaces, state.hover and state.pressed; overlay.stroke on overlay.halo over black and over white |
3 | 4.5 |
State cues: accent.border (the outline of a selected or on control) on the control surfaces; overlay.handle_stroke on overlay.handle_fill (a selected anchor against a hollow one); the data channel colours (data.red ... data.yellow) on surface.sunken (a curve editor's plot) |
0 (listed, never warned) | 4.5 |
The thumb of a canvas scroll bar (text.faint, text.muted) on its track (surface.chrome) |
0 (listed, never warned) | 3 |
Component styles in craft-ui derive their state fills from these tokens. In high contrast a selected or on state is identifiable (WCAG 1.4.11): a fill, an edge or a mark reaches 4.5 on what it sits on. Where a fill carries the state alone, it moves along OKLCH lightness to the nearest step that does, with its text still readable on it (craft_theme::Identify, identifiable_outline). The hover fill of a list row stays at least 1.12:1 from the rest surface and from the selected fill (visible_hover), so the mouse cue always shows. Standard contrast keeps the theme's own fills and has no minimum for these cues.
Hover, pressed, dividers and disabled text have no rule, and control edges have none in Standard, so they take their derived
or pinned values in Standard contrast (and in High contrast, for hover, pressed, dividers and disabled text), as do the guide colours and overlay.line, the bare accent
line of a transform box, path outlines, a pen draft and warp boundaries: a bare line on an image
can't promise a ratio. overlay.handle_stroke follows overlay.stroke, pinned or not, and the
contrast pass moves it from there as far as overlay.handle_fill needs; so a theme that pins an
overlay.stroke failing on the white handle fill gets handle outlines off its pin, and no
warning names them. A translucent fill is measured over surface.panel.
text.on_selected defaults to text.normal's ramp step, so a neutral selection looks like the
rest of the text and a coloured one (a navy or blue selection) gets its own readable text.
text.on_strong is white, and accent.strong is accent.solid with only its OKLCH lightness
moved, as far as white text needs to reach the minimum: the accent itself where white already
reads on it, a slightly deeper accent where it doesn't (Pro's dark #378EF0 becomes #1B77D7). A
accent.strong_hover and accent.strong_pressed are accent.strong with its lightness moved away from the text (darker under white text) by the distance accent.hover and accent.pressed lie from accent.solid, in every appearance, so the three fills differ and the variants read wherever accent.strong does. Accent fills that carry text use the strong pair; fills without text (check marks, slider fills) use accent.solid. A
pinned accent.strong stays in standard contrast; unpinned text on it turns black where white
misses, as on the other solid fills, and pinned text that misses is reported.
| Standard contrast | High contrast | |
|---|---|---|
| Unpinned colour that misses | moved to the minimum | moved to the minimum |
| Pinned colour that misses | kept, reported as a warning | fixed, pins included |
| Pinned text on solid fills that misses | kept; the unpinned fills under it move | fixed, pins included |
| State fill under text that cannot reach 7 | n/a | the fill moves away from the text, as far as needed |
A failing pair is reported once, as the semantic pair.
A theme with contrast_intent: standard should resolve with no warnings; built-ins do in both
contrasts, except the soft themes in standard contrast.
Selection
The suite has one selection, in selection.json of the suite folder. Each field is set once a
user picks it in some app; unset fields come from each app's own defaults, so one app's default
never reaches the others.
{ "schema_version": 2, "revision": 17, "library_revision": 4,
"suite": { "theme": { "light": "craft.artcraft", "dark": "craft.graphite" },
"mode": "system", "contrast": "system", "size": "compact", "text_size": "default" },
"written_by": "pdfcraft 0.15.0" }
| Field | Values |
|---|---|
suite.theme.light, suite.theme.dark |
a theme id per mode; each slot optional |
suite.mode |
light, dark, system |
suite.contrast |
standard, high, system |
suite.size |
compact, comfortable |
suite.text_size |
small, default, large, larger |
- Picking a two-variant theme sets both slots; a single-variant theme sets only its own mode's slot.
- Version 1 files (
suite.themea string,modeonly) are read by putting the theme in both slots; the next write is version 2. Aschema_versionof 3 or above is refused and never changed. Keys the app doesn't know are kept on every write. - No
selection.jsonmeans nobody has chosen anything. An app writes it only when the user picks, never on first start.
In an app
SuiteChoice::with_defaults(&AppDefaults)fills the unset fields from the app'sAppDefaults { theme: ThemePair, mode, size, sizes: AppSizes }.sizesis the app's own size overrides, read from itssizes.jsonwithAppSizes::parse: base values (size.control.md,space.gap.row,radius.button,typography.body.size) that derived sizes follow.all,compactandcomfortablehold the paths; a size set's own map wins overall. Themes don't set sizes.- Each app keeps an
AppChoice { theme, mode, size }in its own preferences for "use a different theme / mode / size in this app";applylays it over the suite's selection. It has noDefault: the app states what a fresh install shows. resolve_selection(&selection, system, fallback_mode, &defaults, app, lookup), withlookupa&mut dyn FnMut(&ThemeId) -> Option<ThemeDef>(&mut |id| store.theme(id)), returnsShown { theme, appearance, resolved, notices }.Systemmode or contrast uses what the OS reports (SystemAppearance); with no answer, mode usesfallback_mode(noticeSystemSilent) and contrast is standard.- An unknown theme id falls back to the app default's slot, then to
SUITE_DEFAULT, with anUnknownThemenotice. A single-variant theme in the other mode's slot shows its own variant (noticeOnlyVariant).
Suite folder and store
SuiteDir::resolve(app_isolated) picks the folder in this order:
CRAFT_SUITE_DIR. Set but empty: in memory, nothing on disk is read or written.- In memory when the app runs without a disk store (
app_isolated: constructors, tests, portable installs). ArtCraft/themesunder the local config folder:~/.configon Linux and the BSDs,~/Library/Application Supporton macOS,%LOCALAPPDATA%on Windows.
Web builds are always in memory, with the same operations.
ArtCraft/themes/selection.json suite selection and revisions
ArtCraft/themes/selection.lock lock file, never deleted
ArtCraft/themes/library/<id>.json one user theme per file
ArtCraft/themes/selection.broken-<unix-ts>.json a damaged selection, moved aside on the next write
Reading never creates anything; the folder appears with the first write.
Writes
Reads take no lock; every write replaces the file by atomic rename. A write takes the exclusive
selection.lock (retries for 2 s, then Busy), reads selection.json, merges, writes with
revision one above the file's, and checks the file again just before the rename.
A damaged selection.json (or one over 64 KiB) is moved to selection.broken-<unix-ts>.json
before the next write. A file from a newer build gives TooNew and stays read-only.
Store::update(base, change) takes the state the user's change was made on and a
SelectionChange with the fields that changed (theme_light, theme_dark, mode, contrast,
size, text_size). Per field:
| Field | Disk | Result |
|---|---|---|
| not changed | anything | disk's value |
| changed | not chosen | mine |
| changed | equal to mine | disk's value |
| changed | another value, equal to base's | mine |
| changed | another value, not base's | conflict: another app chose it after the caller read |
A conflict returns Conflict { disk, mine } and writes nothing; the app offers "Apply mine".
A change naming a library theme that no longer exists is NotFound.
Library operations take the same lock and bump library_revision:
- Import validates the file and writes its original bytes to
library/<id>.json, never replacing a file (IdExists); "import as copy" picks the first free<id>-2,<id>-3... - Delete refuses built-ins and a theme in either suite slot (
InUse). - Export returns a library theme's stored bytes, or a built-in written as a theme file.
Ids a user couldn't create (craft. prefix, device names) are NotFound and never reach the
file system. A failed write is undone and the error returned.
Watching
Apps use SuiteWatch::open(dir, options, wake), which owns the store on a worker thread and
publishes an immutable Snapshot (accepted, index, active, app_theme, problems,
results, generation). The worker checks the stamp of selection.json and of the themes in
use every 500 ms, compares bytes every 10 s, and lists the library only when library_revision
changes or on Op::Rescan. Each change publishes a snapshot and calls wake once.
Each frame the app compares generation() (one atomic load) with its cache key and rebuilds its
styles only when it changed. Changes go through request(Op): Update, Import, Delete,
Export, Rescan and AppTheme; the result appears in snapshot().result(id). SuiteWatch::memory()
runs without a thread, applying each request before it returns.
The lock file and revision protocol follow pdfcraft#1090.