Design system
The desktop app draws every screen from one scale and one set of components, so sizes, buttons
and gaps are the same everywhere. The scale lives in crates/ui-egui/src/theme.rs; the
components live in crates/ui-egui/src/widgets.rs (icon buttons in icons.rs). Screens never
write a size, a padding or a colour as a number: a test in theme.rs
(screens_take_sizes_and_colours_from_the_scale) walks the source and fails when one does.
The scale (theme.rs)
| What | Names | Values |
|---|---|---|
Headings (Figtree semibold, theme::heading) |
TITLE, SECTION, CARD |
26, 18, 16 |
Text (Figtree regular, or medium through theme::medium / label_text) |
LEAD, BODY, SMALL, LABEL, CAPTION, TINY |
17, 15, 14, 13, 12, 11 |
Code, paths and numbers (JetBrains Mono, theme::mono) |
CODE |
12.5 |
| A wrapped paragraph's line height | theme::leading(size) |
1.45 × the size |
Gaps (ui.add_space, item spacing) |
space::XXS … space::XXL |
2, 4, 8, 12, 16, 24, 32 |
| Padding inside frames | pad::MENU, TIGHT, PANEL, CARD, ROOMY, ROW, BAR, CHIP, GUTTER, FIELD, FIELD_COMPACT |
built from the gaps |
| Icons | icon::XS … icon::XXL |
12, 14, 16, 20, 24, 32 |
| Corners | Tokens::radius_sm, radius, radius_lg |
4 (segments, rows of a list), 6 (controls, fields), 8 (cards, dialogs); status pills are fully round |
| Colours | Tokens (Tokens::get(ctx)) |
one set per theme; contrast is tested |
TINY is for the Advanced workbench's dense lists; everything else is 12 pt or more.
Fonts
Text, labels and headings are Figtree, one variable font file set to three weights (400, 500,
600). Code is JetBrains Mono. Both are in assets/fonts with their licences
(ATTRIBUTION.md). Figtree covers Latin and extended Latin only; every other script comes from
craft-fonts, which release and CI builds embed (CRAFT_FONTS_DIR, see
localisation). A local build without it shows those scripts as boxes.
Control sizes
ControlSize ties a control's height, label size, side padding and icon size together, so two
controls of one size always line up.
| Size | Height | Label | Icon | Used for |
|---|---|---|---|---|
Small |
24 | LABEL |
14 | toolbars, rows of a list, the workbench |
Medium (default) |
32 | BODY |
16 | buttons, switches, dropdowns and their rows, compact fields |
Large |
40 | BODY |
16 | a screen's main switch, full text fields |
Hero |
48 | CARD |
20 | the one action a screen is for (Start) |
A button's label, a dropdown's value, a row of its list and the text typed into a field are all
BODY, the size of the text around them. egui's own controls (dropdowns, menu rows) are set up
in theme::apply to match: Medium in Simple mode, Small in Advanced.
Surfaces and edges
- The page is
canvas, a card on it iscard, and anything to type in or press isfield: a shade lighter than the card (white on the paper card in the light theme), so it reads as something to use.hoverandpressedare a step lighter again. - Every control has the same edge:
card_borderat rest,field_borderunder the pointer, the app colour while it is pressed, open or typed in.field_borderis the 3:1 colour; at rest a field is told apart by its lighter fill and soft edge, not by a 3:1 border. - Keyboard focus is a hairline in
accent_inkon the control's edge and a soft 3 px halo outside it (focus_ring). A text field gets the same, faded in and out (text_focus_ring, drawn once a frame for whichever field has focus).
Components (widgets.rs)
| Need | Use |
|---|---|
| The main action of a screen or card | primary, primary_icon |
| Any other action | secondary |
| A quiet action (no box until hovered) | ghost |
| Something that deletes or can't be undone | danger (filled in the danger colour) |
| Another size, a disabled state, or the full width of a panel | Button::new(kind, label).icon(..).size(..).enabled(..).wide() |
| An icon on its own | icons::button(ui, name, ControlSize, selected, tooltip) |
| A list of things to do with what's shown (a panel's actions) | action_row, one per row, in a card with pad::TIGHT |
| A link in text | link; inside a caption, caption_link |
| One of a few choices | segmented(ui, options, selected, ControlSize): the chosen segment's card slides to the one picked. Big choices with words: choice_tile |
| One of many choices | dropdown(id) (egui's combo box, set up) with a menu_item or menu_choice per row |
| A row of a menu | menu_item |
| On/off | toggle |
| A text field | egui::TextEdit with .frame(text_field_frame(&t)) (Large) or text_field_frame_compact (Medium). One inside a bigger box that shows focus itself calls frameless_field |
| A status word | pill; how sure we are: confidence_badge |
| A box around content | card (screens), panel (workbench) |
| A section's caption | caption |
| A name and its value | stat_row |
| Nothing to show yet | empty_state |
| Work in progress | Spinner, ProgressBar, working (never egui's own: they redraw every frame) |
Every component paints its hover and pressed states with a short ease (hover_t), a focus ring,
a disabled state where it has one, and names itself for screen readers. Labels are translated
inside the component: pass the English key. A row of a list (menu_item) shows its text as
given.
Behaviour
- Scrolling. One notch of the wheel moves
theme::WHEEL_STEPpoints (100) and eases there. Scroll bars are a slim thumb with no track that thickens under the pointer (theme::scroll_style); the thumb keeps 3:1 against every surface. - Lists that open. A dropdown's list and a menu fade in (
POPUP_FADE), show about nine rows before they scroll, and are as wide as their widest row. - Messages. A message to the person (
CraftApp::toast) shows as a compact card under the title bar, in the middle. The card lets clicks through to what is under it; only its close button takes one. A confirmation goes away by itself, and a new one takes the place of the one before it. Errors stay until dismissed. - Text. Glyphs sit on whole pixels (
subpixel_binningis off), which keeps small text sharp on a display at 100 %. - The window. Without a native frame the app draws a 1 px edge in
card_border. On Windows the top side is left to the line Windows draws itself.
Rules
- A new size, gap or colour is a change to the scale, not a number in a screen. If nothing on the scale fits, the design probably wants one of the existing steps.
- A size worked out from another (
body.size + 2.0, a title bar size times its zoom) is fine. - Padding with four different sides (a prompt box that leaves room for its buttons) is written
as
Margin { .. }where it is used; even padding comes frompad. - A paragraph that wraps sets its line height with
theme::leading; a single line doesn't. - Rows of a dropdown or a menu are
menu_items; don't useui.buttonorselectable_labelfor them. - The title bar follows the window's chrome (and, on macOS, keeps its size when the app zooms),
so it scales the same tokens instead of using
ControlSize. - Check a change in both themes:
cargo run -p craft-anything-ui-egui --example snapshot -- --out-dir <dir>renders every scene, and--lightrenders them in Studio Light.--scale 1shows what a display at 100 % shows. The README's pictures come from the same scenes (the example's header says which).