# 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](localization.md)). 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 is `card`, and anything to type in or press is `field`: a shade lighter than the card (white on the paper card in the light theme), so it reads as something to use. `hover` and `pressed` are a step lighter again. - Every control has the same edge: `card_border` at rest, `field_border` under the pointer, the app colour while it is pressed, open or typed in. `field_border` is 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_ink` on 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_STEP` points (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_binning` is 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 from `pad`. - 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_item`s; don't use `ui.button` or `selectable_label` for 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 ` renders every scene, and `--light` renders them in Studio Light. `--scale 1` shows what a display at 100 % shows. The README's pictures come from the same scenes (the example's header says which).