Files
craft-anything/docs/design-system.md

122 lines
7.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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).