MixOS GUI app style guide

1. The three rules

1. One look per window context. Install the theme once per egui context (one for a single-window app). Read everything back from the context. Thread nothing.
2. Tokens and widgets, never literals. A length is a token. A colour is a role. A control is a toolkit widget.
3. The look is on the Bus. Every app answers <app>.look, publishes <app>.look.changed, runs view.look.preview and view.theme.set, and follows the session's tunables through settingsd without a restart and without polling.

2. Crates and dependencies

An app is two crates: an engine crate under apps/<app>/crates/<name> that knows nothing about egui, and the egui shell crate apps/<app>. The shell crate's Cargo.toml lists, as busviewer's does:

[dependencies]
eframe.workspace = true      # the window
egui.workspace = true        # labels and layouts the toolkit does not wrap
toolkit.workspace = true     # theme, chrome, widgets, commands, drive verbs
settings.workspace = true    # the session look follower
citizen.workspace = true     # the Bus connection
bus = { workspace = true, features = ["native"] }   # the native client citizen is built on
futures.workspace = true     # the connection's delivery stream
serde_json.workspace = true  # verb bodies

[dev-dependencies]
egui_kittest.workspace = true  # offscreen snapshots and accessibility queries

The toolkit does not re-export egui or eframe. The engine crate depends on none of these; the layering table (apps/layers.conf.mix) refuses egui, eframe, egui-wgpu, winit and rfd in its closure. A nested GUI crate (a renderer that draws into a texture) is held to this guide and its gate like the shell.

3. The minimal app

The full example is libs/toolkit/examples/guide_app.rs. Its shape, which every shipped app shares:

• Start: citizen::start_with_topics(app, service, url, topics) with the settings summary topic gives the Bus handle and a stream of deliveries; Theme::load() gives the theme file or the embedded design; toolkit::install(ctx, &theme) and drive::install(ctx, app) are called once in the eframe creator; the app's strings are Strings::new over its embedded Fluent catalogue.
• Forwarder: one thread drains the delivery stream into the shell's inbox and calls ctx.request_repaint() for every event, so an idle window wakes for a settings hint, a Bus command or a disconnection.
• App::logic (eframe's per-frame hook before drawing) drains the inbox: Connected, Changed and a summary Topic hint ask the follower for a read; Disconnected resets the follower (so the next connection reads afresh and gets an identity-bearing look even at an unchanged revision), voids retries and clears the authority and any preview; Command is served (<app>.look and <app>.execute through the look layer, then the shipped drive layer's request, whose queued answers come back from drive::logic each frame); a read's answer goes to looked, whose returned next read is sent exactly as returned; a transient fault arms one bounded retry.
• install_theme is the only place the look changes: the follower's inputs for this app (or the theme file) with the window's own choice laid over, installed on the context; every call bumps the window's look generation and publishes <app>.look.changed; it clears a preview, except when it is the arrival of the window's pinned source, which keeps the preview. Before installing, it checks the window's final token pair against the design's constraints; a violating pair is not installed, the last valid look stays, and <app>.look reports the violation.
• App::ui draws the title bar on the root Ui with toolkit::titlebar::show (no stroke argument; it reads the context) and the content inside egui::Frame::central_panel.

What the lifecycle guarantees. The first read happens at start; every later read is caused by a summary delivery, a connection event or a retry; a delivery is never trusted on its own; an older revision never replaces a newer one (the follower checks); without settingsd the theme file stands. There is no timer.

Which design the app draws. The profile's pinned design source. When the summary's source digest (BLAKE3 of the source bytes, settings::source_digest) equals that of the design the binary carries, the app compiles that; otherwise it fetches the pinned source once with settings.source, verifies it with the same digest, caches it per user in a private directory it has checked it owns, and compiles it for the window's own axes, drawing the embedded design until it arrives. A reply activates only for a window that still wants that digest, resolving the window's current inputs and keeping its current preview; a late or superseded one only fills the cache. One fetched source serves every window and light region of the app without another fetch. <app>.look reports which was compiled and the acquisition state. A profile with its own design source is therefore an ordinary profile: the session look, tunes and previews apply. An app connects to the broker over the local Unix endpoint when one is named, which is what lets the compositor attribute its windows; over TCP it works the same but its windows draw the session look under server decorations.

Reading the look in view code.

Never pass any of these into a function as a parameter.

Desktop icons share the context's canonical 1.5 stroke on the 24-unit icon grid. Use icons::image_of or the toolkit icon widgets. Older test fixtures that passed 2.0 explicitly use the canonical default too. The existing appearance.icon_stroke session choice remains supported.

Local style overlays are fallible: handle Theme::with_overlay and Theme::with_choice errors before installing a look. A refused overlay must leave the installed look intact. canvas_dot_pitch accepts 4 to 1000 points, preventing zero or impractically dense drawing loops. For a colour tunable with a numeric range, the bounds apply to each normalised colour component. The value itself remains a hexadecimal colour; icon_mask requires every channel to be at least 0.1.

fn view(ui: &mut egui::Ui, engine: &Engine) {
    let space = toolkit::space::of(ui.ctx());
    let p = Chrome::of(ui.ctx()).palette;
    ui.label(format!("Count: {}", engine.count));
    ui.add_space(space.md);
    ui.add(toolkit::button::IconButton::new(Icon::Settings).tooltip("Settings"));
    ui.add(toolkit::text::dim("dim text"));
    let _ = p.accent;                               // read where you paint
}

4. Which toolkit widget for each need

A plain ui.label is fine. When no widget fits, write it in the toolkit, not the app: read its colours and lengths from Chrome, name the spec section, snapshot it, then use it.

5. The form row

Labels outside the field in one right-aligned column as wide as the widest label the form can show; form_label_gap to the field; trailing controls right to left form_trailing_gap apart; the field takes the remainder; rows form_row_gap apart; the label's id is the field's accessible name.

let form = toolkit::form::Form::new(ui, &["From", "To", "Cc", "Subject"]);
form.row(ui, "To", |ui, label_id| {
    ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
        if ui.add(IconButton::new(Icon::Copy).tooltip(cc_hint)).clicked() { /* ... */ }
        field::text(ui, &mut to, "", ui.available_width()).labelled_by(label_id)
    })
});

A row taller than a field uses row_of with its height.

6. Spacing

ui.add_space(space.md) is the approved form; the gate refuses a literal argument, not the method. An app never sets item_spacing, button_padding or interact_size, and never calls spacing_mut, visuals_mut, style_mut or any Context style setter.

A const is allowed only for content geometry (a column width, a thumbnail edge, a glyph size in a custom painter), named in capitals, commented, and listed in the app's style-allow.conf.mix with the reason.

7. Scroll areas

toolkit::scroll::Area::vertical("messages")      // the id salt: stable, unique in the window
    .max_height(h)
    .stick_to_bottom(true)
    .show(ui, |ui| { /* rows */ });

Also Area::horizontal, Area::both, .min_scrolled_height, .scroll_to(rect). It wraps egui's scroll area, so drag, page click, wheel, keyboard, nesting and two-axis behaviour are egui's; the toolkit supplies the defaults (no auto-shrink) and the style's bar: thin floating bars 4 pt at rest and 10 pt when hot, or solid 6 pt in a bevelled style, the handle in the state's text colour at the resting opacity, the track only while hot, all from tokens. Clippy refuses every egui::ScrollArea constructor by path.

8. Icons

Lucide, from the toolkit's Icon enum. A new icon is added to the toolkit (copy its SVG from the pinned Lucide release into libs/toolkit/assets/icons/, list it in icons.rs), never embedded in the app. Icons take the stroke installed on the context and the colour of the text around them. Sizes: IconButton is the icon_button token (28) with the icon at 52 %; an inline icon uses space.lg or an allowlisted content constant through paint_icon.

9. Menus, context menus, the palette, the Theme menu

Every action is a registry command with a stable id, a label key, a menu path, an optional default chord and typed parameters. The toolkit generates the menu bar, menus, context menus and palette from the registry. Right-click rows are 24 pt and flush. The View › Theme submenu is toolkit::theme_menu::register: its rows are commands, and view.theme.set {scheme?, style?, mode?, decorations?, captions?} is the same choice for agents. An app writes no theme verb of its own. The window's choice reaches the compositor too: a server-decorated window's title bar is drawn from the window's own look, attributed through the broker's record of the app's connection. A multi-window app's extra windows are matched by their toplevel tag once the toolkit sets one; until then they draw the session look under server decorations.

10. Dialogs

dialog::Dialog::new(id, title) with Choices carrying a Role so button order, Enter and Esc follow the platform rule. Wide dialogs use .width; resizable ones .resizable(default, min). A destructive prompt opens with its default focused and ringed.

11. Content regions

Chrome is what the toolkit paints from Chrome. Content is what the person reads or edits. Content keeps its own colours on purpose, but it is on the look:

• a prose region drawn with content::surface takes the person's content settings (padding, font, light). A region with light: true draws the installed window's design, scheme, style and overlays (tunes and preview included) with only the mode forced to light; one with light: false inherits the window as it is;
• an editor palette is built from the region's theme (editor::Palette::from_theme), never from literals;
• a terminal grid draws the terminal.colors settings over the design's colour table for the session's scheme and mode, with the running program's palette changes over them until it resets them, and explicit RGB cells as sent.

<app>.look reports every content region under regions: a prose or editor region with the palette and font it draws with; a terminal region with its design defaults, the settings entries, the runtime overrides in force, the effective palette and its cursor rule.

12. What is forbidden in an app (and what checks it)

Clippy, by resolved path (an alias or a use cannot dodge it), and tools/style_gate.mix, for literals and shapes, refuse these in every egui-dependent crate under apps/, tests excluded:

Each refusal prints the file, the line and the replacement. The example app and the snippets in §3 to §7 are the gate's passing fixture; one adversarial fixture exists per refusal. The gate runs with the other repository gates and in CI.

13. What the app exposes on the Bus for its look

The toolkit provides these; the app lists them in app.describe with its drive verbs and registers them in the verb registry:

• <app>.look (query; {context?} for apps with several contexts): the authority identity (binding, incarnation, revision, source digest, or null while settingsd is missing), the window's look generation, which source was compiled and how it was obtained, the axes with sources (session, app, window), every style token and chrome role with value, default, source (design, design-default, legacy, session, app, preview, accessibility) and shadowed, each role's owning egui slots, each colour's checked flag, the fonts actually drawn, tune.unknown, the preview state, and regions.
• <app>.look.changed (topic): published on every install with the window's context and generation. The compositor follows it for server-decorated title bars.
• view.look.preview (command, intent): params {tune: {"style.field_radius": 3}, expect: {incarnation, revision, generation}} overlay this window only; {tune: {}} clears; refused stale_preview unless all three fence values match what the window draws now; at most 4096 bytes; cleared by every look change except the arrival of the window's pinned design source, which keeps the preview and re-applies it over the refined look. Run through <app>.execute, journaled like any command.
• view.theme.set (command, intent): the window's own axis choice.

To change the session for every app, a caller writes settingsd: settings.validate to try, settings.apply with "tune.style.field_radius": 4 (fenced on the current revision; null resets; "tune": null resets all), settings.reset, or Prefs' prefs.appearance.set. Per app: "apps.<id>.tune.<family>.<name>". Terminal colours, session scope only: "terminal.colors.ansi.1": "#ff0000", "terminal.colors.foreground", .background, .cursor. Style and chrome tunes have session, app and window scope; terminal colours have session scope. A relation between two tokens (a resize corner at least as large as the edge) is a constraint checked on the final layered values and refused with both sides named. Every running app follows within one summary delivery, under any design source. Undo is the caller's held before-values applied as an inverse fenced on the accepted receipt's incarnation and revision; a conflict means someone else wrote in between.

14. Snapshots and tests

• Every view has an offscreen snapshot in the app's tests/, rendered in at least Studio dark and one light scheme. Look at the image.
• Rows are found by accessible name, never by position.
• A registry test checks the verbs the app describes are the ones it registers, including <app>.look and the <app>.look.changed topic.
• A theme-follow test feeds a look delivery with a tune and asserts Chrome::of(ctx) changed; one with ui.reduced_motion asserts the animation time is zero; one with a stale preview fence asserts refusal; one with a pinned source digest that differs asserts the embedded design first and the acquired source after; the lifecycle tests the example app carries run against the shell.

15. Review checklist

• toolkit::install is the only look installer; no view function takes a stroke, theme, chrome or palette parameter.
• The shell follows the example app's lifecycle: forwarder wakes on every event, the follower's returned read is the one sent, a disconnect resets the follower and clears authority and preview, a fault retries once, a differing source digest is acquired.
• No raw egui widget or style setter from §12; clippy and the gate are green with no lint exception inside the app.
• No spacing literal; every const is allowlisted with a reason.
• No colour literal; coloured text goes through toolkit::text.
• Forms use toolkit::form; labels are the fields' accessible names.
• Scrolling uses toolkit::scroll::Area with a stable id salt.
• Icons come from Icon; new ones were added to the toolkit.
• Every action is a registry command; menus and the Theme menu come from the registry; no app theme verb.
• <app>.look, <app>.look.changed, view.look.preview and view.theme.set are described and registered.
• Content regions use content::surface and are reported under regions.
• Snapshots exist for the changed view in a dark and a light scheme, and were looked at.
• Nothing names a host, an operator path or a reference application.