I’ve spent most of my career building things for the browser.
If something looks wrong, you open DevTools.
If spacing is off, you inspect the DOM.
If the layout is cursed, you tweak CSS until it stops yelling at you.
So naturally, I thought building a Terminal UI (TUI) would be… similar.
It was not!
This post is part of me building in public while working on a project called TurboStream — a developer tool that lets you connect high-velocity WebSocket streams (blockchains, BGP, finance feeds, etc.) to LLMs without draining tokens or crashing your system.
Think:
WebSocket → Cache → Triggers → LLM → Short human-readable alerts.
The backend was the easy part.
The Terminal UI nearly ended me.
Coming From the Browser World
In the web world:
- Figma → HTML/CSS is mostly mechanical
- Layout is visual
- Debugging is interactive
In Bubble Tea land:
- Layout is math
- Padding is vibes
- “Why is this box 2 columns wider?” is a philosophical question
There’s no DOM inspector.
There’s no “hover to see bounding box.”
You change one lipgloss.Style() and suddenly everything shifts.
The Hardest Screen: AI Analysis
The screen that caused the most pain was the AI Analysis panel.
Conceptually, it’s simple:
- show LLM context size
- show token usage
- show generation timing
- stream output text
In reality:
- content height changes constantly
- widths need to stay aligned with sibling panels
- scrolling text + borders + padding fight each other
I kept ending up with:
- truncated text
- panels overflowing by 1 character
- borders misaligned depending on terminal width
It looked fine at one size, then completely broke when resized.
If you’ve used Bubble Tea, you know the feeling:
“This should work… why doesn’t it?”
What I Learned (So Far)
A few lessons that finally started to click:
1. Stop thinking in pixels
Terminal layout is about constraints, not visuals.
Everything is rows × columns. Nothing is free.
2. Measure everything explicitly
If you don’t calculate width/height yourself, Bubble Tea will happily surprise you.
3. Borders lie
Borders and padding count.
That “one extra column” is always your fault.
4. Debugging TUIs requires instrumentation
I started adding:
- temporary background colors
- width/height labels inside boxes
- fake content to stress layouts
It felt ugly — but it worked.
What I’m Doing Next
To make this sane long-term, my next steps are:
Create a layout debug mode: Toggleable overlays that show component boundaries and sizes.
Write small layout test harnesses: Instead of debugging inside the full app, isolate one view at a time.
Standardize layout contracts: Every panel declares what it needs instead of “figuring it out.”
Accept that TUI UX ≠ Web UX: Different medium, different rules