00 / Vision
Faithful to SwiftUI, native to the terminal.
TerminalUI is a Swift package for building terminal user interfaces with an authoring model, layout model, and runtime contract that are deliberately shaped after SwiftUI.
The project implements the SwiftUI subset needed to build strong terminal applications without shortcuts in the layout algorithm, state model, or render pipeline. The goal is not to mimic SwiftUI cosmetically — the goal is to preserve the parts of SwiftUI that make large UI codebases predictable.
The deviation rule
Deviations from SwiftUI are permitted only when all of the following are true:
- The deviation is well-considered and explicitly justified.
- The deviation solves a real terminal problem, not a copy of another TUI framework's habit.
- The deviation is documented and reflected in the public API inventory.
When SwiftUI precedent and terminal-native practice disagree, TerminalUI keeps the SwiftUI-shaped authoring story only if it still produces a good terminal experience. If a direct translation would create page-like, mouse-centric, overdecorated, or otherwise non-native terminal behavior, the framework reinterprets toward the terminal-native default.
Confirmed deviations today
Tree-forward collection presentation
Hierarchical lists and outlines are more central in TUI software than they are in typical SwiftUI apps. TerminalUI treats tree-style presentation as first-class while staying close to OutlineGroup's vocabulary.
Repo-owned @Bindable
Ships its own bindable wrapper to keep observable editing on the same invalidation path as @State and the rest of the runtime.
Terminal-native reinterpretation of defaults
Automatic chrome, app-shell composition, and navigation-oriented surfaces may diverge from desktop SwiftUI precedent when modern terminal UX has a clearly better answer.