Honor the grid#
Compose in character cells. Don’t transplant desktop widgets into a keyboard-first surface.
A design study for llama-deck
The terminal rewards restraint.
The strongest TUIs feel dense, calm, and unmistakably native to the character grid. Their polish comes from hierarchy, alignment, semantic color, and instant response—not from adding more chrome.
3evidence streams
857GitHub stars surveyed locally
1code-level interface review
Method. This study combines terminal-community discussions around r/unixporn aesthetics, a local aggregation of Nick’s starred repositories extracted September 11, 2026, and a static review of llama-deck’s src/ui layer on September 15, 2026. The application was not run live.
Ten rules of a convincing TUI
High-confidence qualitative patterns repeated across independent community discussions. They were not counted as a formal survey.
Information first. Decoration last. Chrome should frame the work, then get out of the way.
Make color mean something#
Use one accent, dimmed chrome, and semantic states rather than a 16-color rainbow.
Border selectively#
Thin rounded borders can signal focus; whitespace and dividers should do most of the structural work.
Keep the map stable#
Fixed panes, one clear focus, and a persistent breadcrumb reduce the user’s cognitive load.
Use glyphs as texture#
Nerd Font icons accelerate scanning, but every icon needs a clean ASCII fallback.
Align ruthlessly#
Right-align numbers, hold fixed column widths, and keep content away from borders.
Teach through the footer#
A one-line contextual hint bar plus ? help makes the interface self-explanatory.
Reveal depth on demand#
Keep the default view quiet; surface power features only when context makes them useful.
Move with purpose#
Smooth graphs and live watch states should communicate change, never merely decorate.
Use familiar grammar#
Vim-style navigation, mnemonic single keys, / search, q quit, and ? help.
Community synthesis: Lobsters TUI discussions, Hacker News threads on btop/Textual/k9s, and unixporn-adjacent workflow coverage.
Quiet chrome, shown
The same information can feel noisy or composed. Toggle the frame to compare the hierarchy.
The refined version keeps status, metrics, and hints—but removes three framing layers and lets spacing establish the hierarchy.
The star graph says “polish”
Nick’s 857-star archive contains roughly 45 curated TUI repositories. The framework mix is broad; the aesthetic signal is much clearer.
Languages across the curated TUI set
Theme repositories
15
Catppuccin dominates
Rose Pine appears twice and Flexoki once. Gruvbox, Tokyo Night, Dracula, Nord, and Everforest are absent from the starred-theme set.
- File managersyazi, joshuto, ranger, superfile—the strongest application cluster.
- AI and agent TUIsgrok-build, veyyon, otui, and opencode.
- Task toolstaskwarrior-tui, taman, epoch, and flow_state.
- Terminal finishtmux configurations, terminalizer, oh-my-posh, exa, zoxide, and emulator projects.
Interpretation: framework-agnostic and application-led, with Go/Charm and TypeScript/OpenTUI as current learning edges. The visual preference leans soothing and pastel, not high-contrast retro.
Source: local GitHub star export extracted 2026-09-11. Counts and repository names come from the research aggregation.
llama-deck has strong bones—and too many frames
The review covered the React shell, screens, components, and themes. This is code-level evidence, not a live usability test.
Current hierarchy
Header boxfull border + app title
Tab barglobal navigation
Screen paneborder + title when focused
Section boxesstatus · meters · throughput · slots
Four simultaneous chrome layers compete with the telemetry they are meant to support.
Chrome overload
Drop the header, screen-pane, and footer boxes. Reserve borders for overlays and the single focused widget.
Titles shout
“SERVER TELEMETRY,” “STATUS,” and “METERS” use volume where dimmed title case would create calmer hierarchy.
The footer spends three rows on one line
Make it borderless and contextual. Keep ? as the complete reference.
Gauges leave precision on the table
Fixed 24-cell bars use only full blocks. Scale with width, add eighth-block resolution, and color thresholds semantically.
Help is not yet safely modal
The fixed 76-column overlay can overflow smaller terminals. Center it, clamp it, and dim the backdrop.
Iconography is missing
Add Nerd Font glyphs for tabs, file types, and states—with ASCII fallbacks and a support check.
Keep these foundations
- Debounced resize relayout, degradation below 100×30, virtualized tables, and ring-buffered telemetry.
- Command palette,
?help, footer hints, and a one-owner focus engine. - Truecolor themes, OSC 52 clipboard support, braille spinners, sparklines, and golden-frame snapshots.
Change plan, in order
Start with structure. Theme and micro-polish matter more after the interface has room to breathe.
De-chrome the shell#
Borderless one-line header and footer; no screen-pane frame.
Make rounded borders the exception#
Use rounded as the default box style, then show it only for focus and overlays.
Move to quiet title case#
Let whitespace, weight, and muted color carry hierarchy.
Repair the theme system#
Correct Catppuccin’s bright foreground; repair or remove Cyberpunk and Matrix; add contrast tests.
Recompose telemetry#
Merge status into the header strip and place VRAM and KV gauges side by side where width permits.
Add glyphs with fallbacks#
Improve scan speed without making Nerd Fonts a hard dependency.
Increase gauge fidelity#
Fractional blocks, responsive widths, and warning thresholds.
Fix the modal geometry#
Center and clamp help, with a dim backdrop.
Read the version dynamically#
Replace the hardcoded v0.1.0 with package metadata.
Themes should preserve meaning
Five themes exist in code: TokyoNight, Catppuccin, Gruvbox, Cyberpunk, and Matrix. The README also claims Nord and Monokai, which creates documentation drift.
Repair Catppuccin
fgBright is Rosewater #f5e0dc; use a near-white Text role in the #cdd6f4 family.
Rework the joke themes
Cyberpunk is harsh for sustained reading. Matrix flattens success and warning into similar greens and makes muted text nearly invisible.
Add taste-aligned options
Rose Pine matches the star signal. Nord and Everforest also broaden the serious, low-fatigue set.
CyberpunkBody text #00f0ff on #0d0e15; muted #4a5171 is weak against that background.MatrixSuccess #00ff41 and warning #a3ff00 are hard to distinguish; muted #003b00 nearly disappears on #050b05.Test ruleAdd programmatic contrast checks, aiming for a WCAG-like minimum of 4.5:1 for foreground/background pairs.A compact design contract
Use this as the review lens for every new screen.
Keep
- Information-dense default views
- One active accent and clear semantic states
- Stable panes and a visible breadcrumb
- Right-aligned numbers and fixed columns
- Contextual hints plus full help
- Fast, differential redraws
Avoid
- A border around every region
- Desktop-widget cosplay
- Hardcoded clashing color
- Glyphs without fallbacks
- Text touching frames
- Flicker and full redraws
Evidence and limits
Each conclusion in this study belongs to one of these three evidence streams.
Community aesthetic
Search-grounded synthesis of Lobsters discussions, Hacker News threads, and unixporn-adjacent coverage. Repeated patterns are treated as qualitative consensus, not measured prevalence.
Starred repositories
Local export of 857 GitHub stars, extracted September 11, 2026. The TUI subset was curated to roughly 45 repositories, with language and theme counts reported directly.
llama-deck review
Static code review of src/ui on September 15, 2026. No live interaction or rendered-frame validation was part of the research pass.
Open question. Because Reddit’s JSON endpoints could not be fetched directly, this study does not claim a quantitative sample of r/unixporn posts. A future live review should also validate the proposed layout at multiple terminal sizes and measure theme contrast programmatically.