UI practices¶
Apps built by one team should look and behave alike: one theme, no colours written as values, disabled controls that say why, no blocking work on the UI thread, the same spacing and wording everywhere. The UI lints check the part of these practices that the source shows. The rest stays a review item, listed below so that a reviewer, or an agent, knows what is left.
Two layers¶
| Tier | What it holds | Combine it with |
|---|---|---|
| ui | The practices of any user interface, as lints that know no toolkit. Each lint names the calls it looks for in parameters; the ui tier leaves the toolkit-specific ones empty. |
a size tier: extends = ["medium", "ui"] |
| egui | Extends ui: fills those parameters with egui's calls and types and the vhrd_egui helpers that replace them, and adds lints that only egui has. |
a size tier: extends = ["medium", "egui"] |
A project on another toolkit extends ui and sets the call parameters for its toolkit in spirit_level.toml, the way the egui tier does.
Which crates are UI crates¶
The UI lints look only at UI crates, and never at test code.
- A crate that depends directly on a UI toolkit is a UI crate. The toolkits are the
toolkitsparameter of each lint (egui, eframe, iced, slint, gtk4 and others by default). - The crate map says it outright:
ui = truemakes a crate a UI crate,ui = falseexempts one that depends on a toolkit only for its types. - The theme crate is where colours and sizes are written as values. The map marks it
theme = true; without a map, crates named like*_themeand files namedtheme.rsor undertheme/count (theme-cratesandtheme-paths).ui-colour-literalandui-size-literalskip it.
[map.crates]
foo_ui = { layer = "app", ui = true }
foo_theme = { layer = "app", ui = true, theme = true }
foo_model = { layer = "model" }
The catalogue¶
One row per practice. Sources: the vhrd_egui UX guide (docs/ux-guide.md, by section) and its app skill, the workspace guideline's lint policy, and how rerun and zed keep their UI code in check. "By review" means no lint can check it honestly; a person or an agent reads the code or the screen.
Any UI¶
| Practice | Source | Check | Confidence |
|---|---|---|---|
| A cut list ends in a fold that opens to every item, never "N more" alone | UX guide §2 | ui-more-count |
estimate |
| A control that cannot be used now stays visible, greyed out | UX guide §2, §6 | by review: a hidden control is code that is not there | - |
| A disabled control says why and what would enable it | UX guide §2 | ui-disabled-without-reason |
estimate |
| Hovering a disabled control highlights its cause on screen | UX guide §2 | by review | - |
| Every control, number and badge has a tooltip that adds to its label | UX guide §4 | ui-tooltip-repeats-label flags a tooltip that only repeats the label; whether it adds enough is by review |
certain |
| An icon-only or glyph button says what it does in a tooltip | UX guide §4 | ui-hover-text |
candidate |
| Related items light up together on hover | UX guide §5 | by review | - |
| Colours come from the theme | UX guide §3; rerun's colour bans | ui-colour-literal |
certain |
| Spacing, sizes, radii and type come from the theme; widths are learned, never fixed | UX guide §3, §6 | ui-size-literal |
certain |
| Status colour never carries meaning alone; categorical colours avoid red and orange | UX guide §3 | by review (vhrd_egui tests its palette) | - |
| Button labels are actions, starting with a verb | UX guide §7 | by review: no word list tells a verb from a noun ("Export", "Status") | - |
| A button that opens a dialog ends in "…", the one character; a button label has no closing full stop | UX guide §7 | ui-label-punctuation, with an exact fix; whether a button opens a dialog is by review |
certain |
| The likely action stands out; a destructive one never does | UX guide §7 | by review | - |
| A tap that throws work away asks first or can be undone | UX guide §7 | ui-destructive-unconfirmed |
estimate |
| Undo covers every edit and names it; interruptions match their weight; a warning sits by its field | UX guide §7 | by review | - |
| The UI thread never blocks: no file, network, process or sleep calls in UI code | UX guide §9; the rust-repo rules; zed's blocking_io_on_foreground |
ui-blocking-call |
estimate |
| UI code spawns work through one wrapper that names it, reports a crash and repaints | the rust-repo rules; workspace guideline §5; rerun's spawn_local ban |
ui-raw-spawn |
certain |
| Slow work shows what runs and how far | UX guide §9 | by review | - |
| Errors say what happened and what to do, in plain words | UX guide §9 | ui-debug-text finds Rust's debug form shown to a person; the wording is by review |
estimate |
| No unwrap or expect on data from disk, the network or the person | UX guide §9 | panic-in-library for library crates; ui-unwrap-external-data for a file, parse or connection call in a UI crate |
estimate |
| Settings and layout survive a restart; transient state is never saved | UX guide §9 | by review | - |
| Everything works from the keyboard | UX guide §8 (planned there) | by review | - |
| Text a person reads comes from locale files | UX guide §2 | ui-locale-strings, opt-in: off until a project translates its UI |
certain |
| The UI keeps its shape; big data stays fast; nothing updates itself unasked | UX guide §6, §7 | by review | - |
| Say why when doing something non-obvious; measure an input, then confirm | UX guide §2 | by review | - |
egui and vhrd_egui¶
The same practices, specialised by the egui tier's parameters, and the practices only egui has.
| Practice | Source | Check | Confidence |
|---|---|---|---|
Colours from ve_theme::Tokens (ui.tokens().colors), never Color32::from_rgb, Color32::RED or hex_color! in app code |
UX guide §3 | ui-colour-literal with egui's constructors |
certain |
Sizes from Tokens (space, radius, stroke, type_scale), widths learned with ve_dash::steady_width, never add_space(6.0) or .size(11.0) |
UX guide §3, §6 | ui-size-literal with egui's sizing calls and Spacing fields |
certain |
add_enabled, add_enabled_ui, disable come with on_disabled_hover_text (on_hover_text does not show on a disabled widget) |
UX guide §2 | ui-disabled-without-reason with egui's calls |
estimate |
Every app installs the shared theme: ve_theme::setup |
UX guide §3 | egui-shared-theme |
estimate |
A status glyph is painted in its tone with ve_theme::status_icon, never a character in a label |
UX guide §3 | egui-status-glyph |
certain |
| A widget's id is unique within its parent: no constant id given in a loop | egui's id rules; vhrd_egui FoldRest docs |
egui-id-in-loop |
estimate |
request_repaint is called by the worker that has news, not by every frame |
UX guide §9; egui's repaint model | egui-repaint-every-frame |
estimate |
on_hover_text and on_disabled_hover_text add to the label, never repeat it |
UX guide §4 | ui-tooltip-repeats-label with egui's label and hover calls |
certain |
Literals passed to label, button, heading and the like come from the catalogue |
UX guide §2 | ui-locale-strings with egui's calls, opt-in |
certain |
A button with no words in its label (an emoji, a status glyph) has on_hover_text |
UX guide §4 | ui-hover-text with egui's button and hover calls |
candidate |
| One egui version in the whole graph | UX guide §12 | duplicate-versions |
certain |
Every widget sits in ve_frame::WidgetFrame; panels use the egui API the version in use ships |
UX guide §6; app skill "Panels" | egui-panel-api for the API egui's own deprecations name (SidePanel, TopBottomPanel, .show on a Context, App::update); WidgetFrame itself is by review |
estimate |
A dropdown of checkboxes is a ve_basics::Checklist, open while ticked |
UX guide §7 | egui-checklist-menu |
estimate |
Labels are not selectable (ve_basics::setup_labels); ids and paths are copyable |
UX guide §5 | by review | - |
A crash at start is recovered with ve_basics::StartupGuard; build info and the app menu sit in the top bar |
UX guide §4, §9 | by review | - |
| Web crates never call the OS clock, threads, files or processes | vhrd_egui AGENTS.md "Web crates" | each crate's clippy.toml (disallowed-methods), run by clippy-build |
certain |
| UI behaviour is tested headless with egui_kittest | UX guide §12 | by review | - |
Web UIs and bot buttons¶
Nothing is built for them yet. These general lints carry over once their parameters name the calls of a web or bot framework:
ui-colour-literal: CSS colour strings in Rust are found already (hex-strings); a web crate names its style builders inconstructors.ui-disabled-without-reasonandui-destructive-unconfirmed: a bot keyboard builder (InlineKeyboardButton::callback) is a label call like a button.ui-more-count,ui-label-punctuation,ui-debug-text,ui-locale-strings: the text of a page or a bot reply is text a person reads.ui-hover-text: a bot button with an emoji label (no text) needs its tooltip or help text named inhover-calls.ui-tooltip-repeats-label: oncelabel-callsandhover-callsname a framework's own calls, the same check applies.
Web-only and bot-only practices (textContent over innerHTML with data; button text from known values, never model output) would need lints of their own over JavaScript or the bot's handlers.