GitCorner

Code

ossartcraftcraftanything🌐
642d5a256791
design-system.mdRendered Markdown

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 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_items; 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 <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).