Interface guidelines

What it is

The WolOS Human Interface Guidelines: one window scaffold, colours and sizes only from design tokens, and the behaviour every app shares.

Why

When every app follows the same structure, people learn WolOS once. Tokens instead of literal values are what let one theme switch restyle everything.

How

Read it before building a WolOS app; the checklist at the end is what reviews check.

Reference

Every app and shell surface follows this. One look, many themes (theme contract, IaraOS ADR 0016). A theme changes tokens, never structure.

1. Structure: one scaffold

Every app window is AppWindow (crates/shell/src/kit). No app builds its own window layout.

┌──────────────────────────────────────────────────────┐
│ [‹ ›]                             [actions] [search] │  Toolbar (36px, glass, draggable), under the 28px compositor strip
├────────────┬─────────────────────────────────────────┤
│ Sidebar    │ Content                                 │
│ 220px      │ (List / Grid / Detail / Editor)         │
│ glass      │                                         │
│ Sections   │                                         │
├────────────┴─────────────────────────────────────────┤
│ Status bar (optional, 24px, dim text)                │
└──────────────────────────────────────────────────────┘

Single-purpose utilities (Calculator, Clock, Screenshot) use AppWindow compact: toolbar only, no sidebar, fixed size.

2. Tokens, never literals

• Colours: --surface --card --text --dim --line --accent --accent-text --control --glass*. No hex/rgb in app code or app CSS.
• Spacing scale: 4, 8, 12, 16, 24, 32. Nothing else.
• Radius: controls 6, cards 10 (--glass-radius-s), windows/panels --glass-radius.
• Type: Inter. Title 13 semibold (toolbar), body 13, secondary 11 dim, large title 22 semibold (empty states, About). No other sizes.
• Icons: symbolic, 16 in rows/toolbar, 32/48/64 only for files and app tiles.

3. Behaviour

• Shortcuts (Super = ⌘): N new, O open, S save, Shift+S save as, W close window, Q quit, F find, Z/Shift+Z undo/redo, C/X/V/A, comma settings, Backspace delete/trash, I info, Space Quick Look (file lists). Same key, same meaning in every app.
• Selection: click selects, double-click/Enter opens, Shift/Super extend. Right-click → context Menu with the same verbs as the toolbar.
• Destructive actions: confirm in a Sheet with the destructive button on the right in destructive style; prefer undo over confirm.
• Long work (> 1 s): progress in place (row ProgressBar or toolbar Spinner), cancellable, off the UI thread. Never freeze.
• Errors: inline, one sentence, what happened + what to do. Root-only actions: the Authenticate sheet (admin), never "run as root".
• Windows remember size, position, sidebar width, view mode (per app, $HOME/.config/wolos/<app>.json).
• Text: sentence case labels, title case only for app names and menu titles. No exclamation marks. Ellipsis "…" when the action asks for more input.

4. Do not

• Re-implement a library component (kit architecture test enforces).
• Hand-roll toolbars, sidebars, headers, cards, list rows, empty states.
• Add app-local CSS beyond layout glue; visual style lives in the library.
• Invent new spacing, colours, font sizes, icon sizes.
• Put actions in the status bar or navigation in the toolbar.

5. Checklist before commit (each app)

1. Root view is AppWindow.
2. Golden test at 900×600 and narrow 480×360 without overflow (kit golden test).
3. Empty, loading and error states rendered in tests.
4. Shortcuts table above wired.
5. VM screenshot compared side by side with Files and Settings: same toolbar height, sidebar width, row height, fonts.

6. Layout check (binding, from IaraKit)

WOL_DEBUG_LAYOUT=1 outlines widgets; WOL_LAYOUT_CHECK=exit exits 1 on any issue (CI and golden tests). Every surface (menu bar, dock, Control Center, Search, lock, login, every Settings page) has golden screenshots at its sizes, passes the layout check, and was visually reviewed by the author before commit.