14 KiB
UI guidelines
AniCraft's interface serves artists in a flow state (see product-principles.md). These rules
keep it professional, calm and predictable. Tokens live in src/theme.rs: colours in T,
typography in Type. Panels never hard-code colours, font families or font sizes; a test
(guidelines_tests in src/main.rs) fails the build if they do.
1. Layout
The layout is familiar to animators: tools on the left, stage in the centre over a darker pasteboard, timeline at the bottom, Properties / Library / History docked on the right, menu bar and edit bar on top, and a status bar at the bottom.
- The most frequent actions are one click away (timeline header buttons, panel buttons) and one key away (registry shortcuts). Everything is reachable from the command palette (Ctrl+K).
- Right-click offers the actions that apply to what is under the pointer (stage, frames, layer
names), with the same labels and shortcuts as the menus (
menus::cmd_item). - Panels virtualize long content (timeline rows and columns); nothing paints off-screen work.
2. Typography: prose vs data
Two families, chosen by what the text is, not by where it sits:
Role (theme::Type) |
Family | Use for | Examples |
|---|---|---|---|
Title |
proportional 17 | Dialog titles | "Delete layer?" |
Heading |
proportional 12.5, bold, sentence case | Panel/section names | Properties, Timeline, Library |
Body |
proportional 13 | Names, list items, menu items, buttons | layer and symbol names |
Label |
proportional 12 | Field labels, status messages | "Position", "Saved…" |
Caption |
proportional 11 | Hints, explanations, footnotes | "Enter confirms · Esc cancels" |
Data |
monospace 12 | Values and readouts | X/Y, scale, rotation, sizes, fps, seconds, zoom %, cursor coordinates, render stats |
DataSmall |
monospace 10 | Dense numeric scales | timeline ruler, playhead number |
DataLarge |
monospace 14.5 | The hero number | current frame in the timeline header |
Key |
monospace 11.5 | Shortcuts and keycaps | Ctrl+Shift+S, F6 |
Path |
monospace 11 | Paths, ids, preformatted text | file locations, licence texts, frame scripts, class names |
Why monospace for data: fixed-width digits don't jitter while a value is scrubbed or played back, numbers line up in columns, and technical readouts read as instruments rather than prose. Pro audio/video tools use the same idea. We adopt the idea only; we don't copy any vendor's typeface.
Never monospace: dialog descriptions, explanations, menu and button labels, layer names, tooltips' prose, error messages and anything a person reads as a sentence. Mixed lines keep their label proportional and their value monospace.
Typefaces (ADR 0005): Inter (prose) and JetBrains Mono (data), both SIL OFL 1.1,
embedded from the shared craft-fonts input (CRAFT_FONTS_DIR, or discovered next to the repo)
as in PhotoCraft. Users can pick any installed system font for the interface and any
installed monospaced font for data in Preferences › Appearance. Roles stay the same; only
the family changes. Interface scale 75–200% is a preference too. The fallback
is egui's bundled Ubuntu + Hack, so builds without craft-fonts still work. Fonts must be
permissive in use and small enough to bundle (≤ 2.5 MB embedded in total). Platform system fonts
are not used for UI text, because they would change metrics per OS.
3. Colour (ADR 0008)
- Graphite neutrals, darkest at the edges:
chrome(menu and status bars) →panel→panel_alt(section headers, alternate rows, windows) →header(buttons at rest) →hover. Text and number fields are inset:field, darker than the panel. The artwork is the most colourful thing on the stage. - Vibrant colour only where it means something, mostly on the timeline: mint
span= frames with artwork, violettween= classic tween, graphitespan_empty= empty frames, redplayhead. Marks drawn on those blocks useink. - One accent, cobalt
accent, for selection, focus and the active tool. Red only for the playhead, errors and destructive buttons (danger). - Text has three steps:
text,text_dim,text_faint. Use the role's default colour unless you are showing a state. - Contrast (checked by
guidelines_testsfor every palette): body text ≥ 7:1 on panels; dim, faint, accent-coloured (accent_text), error and ok text ≥ 4.5:1; text on filled buttons (on_fill) and on the active tool (on_active) ≥ 4.5:1; marks on timeline blocks and the playhead flag (ink) ≥ 4.5:1; focus rings, selection, checkbox edges and timeline blocks ≥ 3:1 against their background. - Three palettes, one set of roles (ADR 0022, ADR 0077): Graphite (dark), Light and High
contrast (Preferences › Appearance › Theme). Code reads
T.role, never a palette by name, and never assumes a colour or a direction: text on an accent fill isT.on_fill, not white; an icon under the pointer isT.icon_hot; a mark drawn across the timeline isT.text, not white, because the panels may be light. A new token needs a value in every palette and a line in the contrast test. Check UI changes with--theme lightas well. - Users bring their own palettes (ADR 0117): a theme file sets colours for these same roles
over one of the three, and is refused unless its text, icons and focus ring reach WCAG AA
(
theme::shortfalls, the table the built-ins are tested with). So a pair of roles you draw together must be in that table, and nothing may assume a role's colour. A new colour role goes incolour_roles!. Accent bars go throughtheme::accent_bar(the one gradient), icons throughicons::paint(the one placeicon_accentis drawn). Check with--theme <file>.jsonas well. - No raw colours outside
theme.rs: add a token.
4. Shapes, borders, spacing and sizes (ADR 0008)
- Corners follow the role of a shape, never one value for everything:
- Structure is square (
theme::SQUARE): panels, dock bands, the timeline grid, its blocks and selections, the stage. These tile against each other. - Controls are softened (
T.rc(), 3 px): buttons, fields, tools, list highlights, swatches, the playhead flag. Geometric and rectangular, but not sharp. - Floating surfaces are rounder: menus and tooltips 6 px, dialogs and windows 10 px, with a soft, tight downward shadow so they lift off the work.
- Round only where the thing is round: keyframe dots, dials, onion-skin marks.
- Structure is square (
- Sections use
theme::section: a full-width header (chevron, bold title, and in panels and dialogs a horizontal rule across the rest of the row) that folds its content away. The whole row is the click target, it takes keyboard focus, and assistive technology hears "expanded/collapsed". Dock sections areSection::Band, groups inside a panel or dialogSection::Rule. Don't separate groups by indentation alone. - Borders separate layout, not widgets. Use
T.borderlines between regions (panels, section headers, the timeline's layer list and grid, the timeline footer) and around popups. Buttons are flat fills with no resting border; hover lightens the fill. UseT.separatorfor fine grid lines inside a region. - Focus is always visible: pressed and keyboard-focused widgets show a 2 px accent ring.
- Checkboxes and radio buttons go through
theme::checkbox/theme::radio_value, which give them a visible edge (control_edge) so the off state does not disappear. - Click targets (WCAG 2.5.8): at least
theme::TARGET(28 px) for every button, row and field; toolsTOOL_BUTTON(40 × 40); timeline rows 28; layer toggles 24 × 24; dialog buttons 32 high. Don't use small buttons. Timeline frame cells (12 px wide) are a dense-data exception: the ruler, rows and the keyboard reach the same frames. - Item spacing 8×6, buttons pad 10×5. Panels pad 10–12 px. Align values in a column using the
rowhelper. - Active states are solid: the active tool is an accent block with a white icon; a selected
list row is
accent_dimwith an accent edge bar; dock sections start with a short accent bar.
5. Icons
- Lucide (ISC licence,
assets/icons/, credited inATTRIBUTION.md): one consistent, open outline set with icons for everything an editor needs. Useicons::paintwith anicons::Iconvariant. The SVGs are parsed with the engine's own SVG path reader and stroked as vectors at the on-screen size (crisp at any interface scale, no rasterizer dependency). - To add an icon: copy its SVG from the Lucide set into
assets/icons/, add a variant and its file tosrc/icons.rs. Prefer an existing Lucide icon (mirrored if needed) to drawing one. When none fits, draw an originalanicraft-*.svgon the same 24 grid with 2-unit round strokes (the Align panel's icons are such originals). - Icons are placed on whole device pixels with whole-pixel stroke widths; tool icons are drawn at the set's native 24 px, where they are sharpest.
- Selection is solid, Subselection hollow (
Icon::solid): the two arrows must be told apart at a glance, as animators expect. - Forms use
theme::form_row/theme::form_note: labels left-aligned in one column, controls in the next, and explanations under the control they explain (under a checkbox or radio button, aligned with its text), never back at the label column. - 18–20 px glyph inside a larger target, the same colour as the text, white on an active (accent) block, faint when it shows an "off" state.
- Every icon button has a tooltip with its name and shortcut. No icon fonts, no vendor glyphs.
6. Feedback and flow
- Every action answers in the status bar (what happened, and "Ctrl+Z to undo" for deletions).
- Long work never blocks the UI (background render, ADR 0002); show the last good state while waiting.
- Drags are one undo step. Values scrubbed in fields are one undo step.
- Destructive actions follow ADR 0004 (tiered confirmation). Dialog buttons name the action ("Delete Layer", not "OK"). The destructive button is red; Cancel is always available and Esc cancels.
7. Keyboard
- Familiar animation shortcuts first (F5/F6/F7, Shift+F5/F6, F8, Ctrl+B, Enter to play,
,.to step), then the platform conventions (Ctrl+Z/S/O/N…). - Where the industry-standard animation defaults and a generic convention disagree, the
animation default wins and the other becomes an alias (
SHORTCUT_ALIASES): Ctrl+Y redoes, Ctrl+Shift+Z removes a transform, Ctrl+↑/↓ arranges, Shift+,/.jump to the first/last frame, Backspace deletes. A test fails if two commands share a chord. - Tool keys are single letters; Shift constrains; Space pans; arrows nudge (Shift ×10).
- Scrolling follows the browser convention everywhere: the wheel scrolls vertically, Shift+wheel (and sideways wheels or trackpad swipes) horizontally, Ctrl+wheel zooms, over the whole panel, not only its empty parts.
- F1 shows every shortcut (generated from the registry); Ctrl+K runs anything.
- Ctrl+F6 / Ctrl+Shift+F6 move focus between the panels (Stage, Timeline, Properties, Library,
Tools); Tab moves within one. A focused button keeps Enter, Space and the arrows; the other
shortcuts still work (ADR 0022,
a11y::keyboard).
7a. Accessibility (ADR 0022, docs/accessibility.md)
- Every interactive thing has a name and a role for screen readers; the AccessKit audit in
src/a11y.rsfails the build otherwise. Widgets with their own text (buttons, checkboxes, menu items) name themselves. Others go througha11y:- a custom-painted control:
a11y::control(ui, &resp, WidgetType::Button, name, on)(also draws its focus ring); - a field, colour well or menu showing a value:
.named("Position X")/.response.set_name("Easing"); - a slider in a form row:
a11y::slider(it names the number field beside it too).
- a custom-painted control:
- Names say what and how: an icon-only control is named like its tooltip's first line, with
the key in effect (
a11y::with_key("Pen tool", key)→ "Pen tool (P)"); repeated controls carry their row ("Lock Hills", "Drop Shadow blur X"). - Pointer-only surfaces are not Tab stops (
a11y::pointer_only()); say in the docs what the keyboard route to the same thing is. - Panels register an anchor (
a11y::anchor) for Ctrl+F6. - Layouts survive the 200 % interface scale: scroll or truncate, never clip controls away.
8. Copy and numbers
- Sentence case for labels and titles; Title Case only for menu commands, matching familiar tools. Buttons are verbs. No exclamation marks.
- Frames are 1-based in the UI (frame 1 is the first). Time is in seconds with two decimals
(
0.50 s). Units follow the number with a space:24.00 fps,1280 × 720 px,78%. - Use "×" for dimensions and "·" to separate inline facts.
8a. Interface languages (ADR 0040, docs/localisation.md)
- Write interface text in English through the macros:
tr!("Save"),tr!("Saved {path}", path = p),trn!("{n} layer", "{n} layers", n);tr_noop!in tables,i18n::twhere they are drawn. Screen-reader names too. - One sentence is one template with named placeholders; never glue translated pieces. Counts
use
trn!, neverif n == 1. - Keys stay English (ids, stored values, engine params); translate at the point of display.
Translated window titles carry an explicit
.id(..). - Leave room: labels must survive text a third longer. Check with
--lang pseudo.
9. Checklist for a UI change
- Uses
theme::text(Type::…)/theme::font/with_type, with no raw sizes or families, and colours, radii and sizes fromtheme(T,TARGET), with no raw values. - Targets ≥
TARGET, focus visible, contrast as in section 3, corners by role (section 4), borders only for layout, groups as collapsibletheme::sections, Lucide icons. - Data in monospace, prose proportional (section 2).
- Reachable by menu, palette and, if frequent, a shortcut and a right-click menu.
- Screenshot checked (
cargo run -- --screenshot shots/now.png,--open <panel>for dialogs), also with--theme high-contrastand--scale 200. - Named for screen readers (section 7a);
cargo test --bin anicraft a11ypasses. - Text goes through
tr!(section 8a);cargo test --bin anicraft i18npasses and a--lang pseudoscreenshot shows no plain English and no cut-off].