# Mountaineer Aesthetics

**Status: deferred.** Open this file when the UX-tuning pass starts. The committed picks in `STACK.md` and `PROFILES.md` were made on engineering and architectural grounds; their *visual and ergonomic surface* (fonts, colors, ratatui geometry, default zellij layouts, bar configuration, lock-screen styling) is still open. This file is the seed for that work.

## Source material

- `references/classic-high-affordance.md` — a style guide for a classic-affordance desktop OS (BeOS / Mac OS Classic lineage). Provided as a sensibility to translate, not adopt literally. Mountaineer has no GUI toolkit and runs a tiling Wayland compositor; some principles port directly, some need re-expression, and some do not apply.

## What translates to Mountaineer

These principles from the source guide land in our register without strain:

- **Spatial consistency.** Tiling layouts are committed KDL files (zellij), `sysop` ratatui screens have stable geometry, the same subcommand opens the same view at the same position every time. Operators learn the layout once.
- **Determinism / zero-latency UI.** Already our posture for engineering reasons (s6 over systemd, podman over docker). Restated as a UX principle: no spinners for navigation, no asynchronous loading states for things the system already knows.
- **Information density / functional whitespace.** ratatui screens favor density and readability over generous margins. yambar is sized for the data it carries, not for breathing room.
- **Visible commands, no hamburger.** zellij's on-screen keybindings, helix's command palette, `sysop info <role>` telling you what fills each role today. Discoverable, not hidden behind gestures.
- **Strict geometry.** Cell-aligned terminal output, no half-cell decorations. Where we do render pixels (lock screen, launcher), pixel-grid alignment is the rule.
- **Typography: clarity over smoothness.** See *Committed picks* below — Mountaineer ships Iosevka, hinted, as the system monospace.
- **User agency / no ambient noise.** Already manifesto territory ("defaults are arguments", no smart re-organization, no telemetry). In the aesthetic register: fnott delivers what an explicit source produced and nothing more; the bar shows facts, not suggestions.
- **Passive response.** Matches "the configuration is the interface." No background auto-tuning, no opportunistic indexing, no surprise.

## What does not translate

- 3D affordance (raised / sunken buttons, top-left lighting model). We have no buttons. The principle the lighting model serves — *every interactive element should look interactive* — is real, but it expresses itself in a TUI as bold/inverse selection, explicit cursor positioning, and color-coded modes, not as drop shadows.
- BeOS-style window tabs. river is a tiling compositor; window decorations are minimal by design. Window identification is by tag and position, not chrome.
- Scrollbars as three-part track + thumb + steppers. TUI tools use single-character scroll indicators. The *principle* (visible, explicit, no fade-on-hover) survives; the *shape* does not.
- Native primitive drawing calls. No GUI toolkit, won't write one.

## Doctrine: surfaces and `sysop`

Mountaineer separates **surfaces** from **operations**. A surface displays facts. An operation changes state. The bar, the lock screen, the notification overlay, and the boot prompt are surfaces — they read out the system, they do not act on it. `sysop` is where operations happen.

This is principle 15 (stable vocabulary, findable names) made concrete. Every non-ok state visible on a surface has a corresponding `sysop <role>` invocation that explains and operates on it. If the bar shows `svc 2 down`, the operator runs `sysop services`. Surfaces never grow click handlers, never grow toggle gestures, never accumulate context menus. The temptation to "just put a quick toggle on the bar" is the failure mode this doctrine refuses.

The benefit is uniform: one mental model for changing the system, one place to look for operations, no per-surface vocabulary to memorize.

## Committed picks

### Palette: flatwhite

Mountaineer ships flatwhite as a coordinated palette across foot, helix, zellij, fuzzel, fnott, yambar, swaylock, and `sysop`. Light theme, warm off-white background, low-saturation accents — a calm, paper-like register that reads as one artifact across the stack rather than seven tools sharing a screen.

Sysadmin OSes default dark by reflex, not by design. Principle 1 forbids the reflex: we picked flatwhite because we think it is the better-designed default, not because it is the safe one. Operators who prefer dark themes override in one line per tool, and we document the override path — but we do not apologize for the default.

A secondary effect: light low-contrast palettes stress-test aesthetic discipline. Heavy chrome, decorative color, and lazy reverse-video selections all read as noise on flatwhite. The ratatui conventions below are partly downstream of that constraint, which is the point.

### Font: Iosevka

`ttf-iosevka` is packaged in Alpine `community/`. Mountaineer ships the standard hinted build as the system monospace for foot, helix, zellij, fuzzel, yambar, and ratatui.

Iosevka is narrow, strongly hinted at small sizes (the source guide's "clarity over smoothness"), and pairs with flatwhite's warm low-contrast register better than JetBrains Mono's wider modern feel. It is actively maintained and meets the Alpine-as-filter test. We ship with ligatures off — operators who want them flip one config line per tool. When Alpine packages an Iosevka Nerd Fonts variant we re-evaluate; until then operators who need Nerd Font glyph coverage install a fallback themselves.

### ratatui screen conventions

Every `sysop` subcommand follows the same skeleton. Learn one, learn all. A small `sysop_tui` crate provides the frame, the footer renderer, the color constants, and the selection widget; subcommands compose those primitives, they do not redesign them.

- **Modal, single-purpose screens.** A screen does one thing. `sysop wifi` is a list of networks; Enter opens a separate detail/action screen for the selected one. No paneled list+detail layouts. Density is preserved, every screen survives an 80-column SSH session unchanged, and the cognitive cost per screen stays bounded. Tradeoff accepted: one extra keypress to see a network's BSSID.
- **Footer-only chrome.** A persistent bottom row shows the current screen's keybindings (zellij/helix register — "visible commands, no hamburger"). No top title bar; the shell context already names the command. No borders around regions; whitespace separates panes and alignment carries the geometry. This is partly downstream of the palette pick — flatwhite punishes heavy line-drawing.
- **Color is state, weight is hierarchy.** Hue is reserved for operational state: green = healthy, yellow = transient/syncing, red = fault, dim = inactive. Titles, labels, and grouping use bold or weight, never hue. Hue is a precious information channel; spending it on "this is a heading" wastes it. Tradeoff accepted: titles look plainer than operators trained on Charm-style TUIs may expect.
- **Selection: inverse + leading `▶`.** Two cues. Flatwhite's contrast is low enough that inverse-only selection can be missed at a glance, and the second cue is free for color-blind operators.
- **Reserved global keybindings.** `?` opens help, `q` quits, `Esc` goes back one level, `/` enters filter/search, `:` opens the command palette. Identical on every screen; subcommands do not rebind them. Helix-influenced and consistent with the rest of the userland.

### yambar segments

The bar is a read-only system surface (see *Doctrine* above). It shows facts; it does not interact.

**Left side:** active river tags only, numbered, unused tags hidden. No window title.

**Right side, in priority order from the edge inward:**

- **Date/time** — `2026-05-17 14:23`. ISO 8601 date + 24h time, no seconds. The format is opinionated; the audience expects it.
- **Battery** — `bat 87%`. Sysadmin (laptop) profile only; hidden when no battery is present.
- **Network** — `wlan0 home-net` / `eth0 ↑` / `net ↓`. Interface name plus state.
- **Audio** — `vol 40` / `vol mute`. PipeWire-sourced.
- **Services** — `svc ok` / `svc 2 down`. s6-rc health summary. Mountaineer-specific.
- **Storage** — `zfs ok` / `zfs degraded`. ZFS pool health. Mountaineer-specific.
- **Conditional segments**, rendered only when active: `vpn wg0`, `dnd` (notifications muted).

**Style rules:**

- Iosevka, flatwhite palette.
- Short role-keyword labels (`bat`, `vol`, `svc`); no glyph-only segments. The role keyword is the findable name, glyphs are decorative.
- Separator is whitespace at a fixed cell gap. No `|`, no `·`. Strict geometry.
- Hue is reserved for non-ok state — red for fault, yellow for transient. The resting bar is foreground-on-background. Same rule as ratatui.

The two Mountaineer-specific segments (`svc`, `zfs`) are why this is our default and not a stock yambar config. They surface the OS's actual posture — service and storage health — at a glance, and they route the operator into `sysop services` and `sysop storage` when something is off.

### river defaults

river ships no default configuration — `~/.config/river/init` is the configuration, executed as a shell script at compositor start. Mountaineer authors this file and ships it as part of the Sysadmin overlay (path TBD; the artifact lives outside this document).

**Modifier.** Super. Matches sway/i3 muscle memory and keeps the operator's tiling vocabulary portable across machines. No surprise wins available here.

**Tag model.** Numbered 1–9, no names. Matches the yambar tag segment and avoids presuming a workflow. Operators who want named tags rename in a personal overlay; the default does not couple the WM to a use case.

**Geometry.** Gap = 0 (strict geometry). Border width = 1px. Border color: flatwhite accent for focused, flatwhite muted for unfocused. No window decorations beyond the border.

**Keybindings: minimal active set, full surface commented out.** The shipped init contains a small set of active binds and the remainder of river's example init as commented blocks grouped by category. This makes the init file a teaching artifact — reading it tells the operator what river can do, not just what we wired up — without committing to defaults we haven't justified. We add binds back by uncommenting; we delete blocks we are sure we will never want.

Active set:

- *Windows.* `Super+Return` → foot · `Super+d` → fuzzel · `Super+q` → close · `Super+h/j/k/l` → focus · `Super+Shift+h/j/k/l` → move · `Super+f` → fullscreen · `Super+Shift+Space` → float
- *Tags.* `Super+1..9` → view · `Super+Shift+1..9` → move window to tag
- *System.* `Super+L` → swaylock · `Super+Shift+r` → reload init · `Super+Shift+e` → exit river to TTY · `Print` → grim full · `Super+Print` → grim region
- *Hardware (laptop).* `XF86Audio{Raise,Lower,Mute}` → wpctl · `XF86MonBrightness{Up,Down}` → brightnessctl

`Super+Shift+e` is the recovery path when a broken init traps the operator inside river; it stays uncommented even though it is rarely used.

### Lock screen (swaylock)

swaylock is styled to read as a continuation of the system, not a separate application. An operator glancing at a locked Mountaineer machine sees the same visual register they left behind.

- Background: solid flatwhite. No image.
- Font: Iosevka.
- One info line above the password field: `2026-05-17 14:23 · hostname`.
- Password field: centered, single line, no avatar, no caps-lock chrome.
- Failed authentication: the field outline flashes red for one frame. No text.

### TTY login

We ship no display manager (manifesto, *What we will not do*). The kernel login prompt stays. Two surfaces are ours to design: `/etc/issue` and the motd.

**`/etc/issue`:**

```
Mountaineer 3.21.0 (Dull Edge) · \n · \l
```

Distro, version, channel, hostname (`\n`), tty (`\l`). No ASCII art, no tagline — the version line is the only branding.

**motd: rotated `sysop` tips.**

On successful login, a single blank line followed by one tip from a small fixed set, rotating per login. The tip set teaches the `sysop` vocabulary by exposure: after a handful of logins, an operator has seen the entire surface. This is principle 15 enforced at the lightest possible touch — the OS reminds you of its own findable names without nagging.

Initial tip set (≤8 entries; rotated per login):

- `sysop info <role>` — show which tool fills a role and where its config lives
- `sysop services` — s6-rc service health
- `sysop wifi` — network connections
- `sysop storage` — ZFS pool state
- `sysop logs <service>` — structured logs for a service
- `sysop help` — list all `sysop` commands

The motd is opt-out, not opt-in. The installer asks once ("Show a `sysop` tip on each login? [Y/n]") and writes the choice. After install, `sysop motd off` / `sysop motd on` toggle it — every surface has a corresponding `sysop` operation.

The set is intentionally small and rotation is per-login, so a regular operator sees the full surface within a week. New tips are added only when a new `sysop` verb appears, and only by replacing an older one. Tips age into noise if they accumulate.

## How this fits the manifesto

The relevant principles already in play:

- Principle 1 (Defaults are arguments) — aesthetic defaults are defaults, too. Every theme, font, layout, and surface convention above is a position defended in writing.
- Principle 2 (Configuration is documentation) — the shipped river init, with commented-available binds, is a teaching artifact. So is the rotated `sysop` motd.
- Principle 15 (Stable vocabulary, findable names) — the surfaces-and-`sysop` doctrine is principle 15 made concrete. The look of `sysop` itself is fixed by the ratatui conventions and stays stable across releases even as underlying tools swap.
- Principle 16 (Tight scope) — the picks above lean on tools whose authors share a design voice (Daniel Eklöf for foot/fuzzel/fnott; the Iosevka and flatwhite authors for typography and palette). We did not ship a configuration framework.

The committed picks above replace what used to be open questions. Further refinement happens in the configuration files themselves (the river init, the swaylock config, the yambar config) and in the `sysop_tui` crate that enforces the ratatui conventions — not by re-opening this document.