Skip to main content
otter-ui is how Otter Shell apps draw UI. For new apps, use Surface Description: build a SurfaceNode tree each frame, let UiFrame lay it out, emit draw commands, and register hit targets. otter-bar and a few older code paths still use widget structs with comptime registries. Everything else (settings, monitor, lock, greeter, new toplevel windows) should use Surface Description.

Two UI paths

Both paths rasterize through the same otter-render CommandList and quad_renderer.

Surface Description in one frame

Documentation map

Surface Description

UiState, frame lifecycle, capacities, text shaping, rasterization.

Layout model

NodeKind, LayoutSpec, SizeRule, rows, columns, grids, scrolling.

Nodes and controls

Every leaf type, its spec fields, and default hit behavior.

Input and overlays

Hit testing, dispatch, focus, popups, tooltips, UniformList.

Drawing primitives

drawing.zig helpers for custom drawing outside Surface Description.

Bar widgets

FieldRegistry, bar widget types, when to skip Surface Description.

Key types

Dependencies

otter-ui links otter-geo, otter-render, otter-theme, otter-wayland, otter-desktop, otter-tools-core, and otter-utils. Load a Theme and Font and pass them through FrameOptions so controls pick up colors from theme.conf.

Reference apps