Tui ui
Design web-like user interfaces in the terminal and inside tmux with a cell-grid Canvas, CSS-like box model, flexbox/grid layout, and 17 reusable widgets such as Panel, Table, Card, ProgressBar, Meter, Tabs, Tree, Badge, Banner, and a braille line chart. Use when an agent needs a dashboard, panel, table, status page, TUI layout, tmux dashboard, screenshot-driven CLI/TUI replica, ANSI frame, truecolor render, pyte PNG screenshot smoke test, wide-character alignment, or a new terminal widget.From its SKILL.md
npx -y skills add dwgx/SmartCLI --skill tui-uiAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
18.3 KB, as published. Nobody here has run it
tui-ui
Lay out a terminal screen the way you lay out a web page: nested boxes with margin,
border, and padding; rows and columns that flex with fr units; and drop-in widgets
(panels, tables, cards, meters, tabs, trees). You compose a tree of renderables, and
the engine resolves sizes, composites cell grids, and serializes once to a
tmux-safe ANSI frame. Everything is display-cell accurate, so CJK, emoji, and
box-drawing never desync your columns.
Pure Python stdlib (optional pyfiglet for the Banner, optional wcwidth for an
authoritative width — a stdlib fallback covers the same edge cases). Output is a
plain string you can print, pipe, wrap in a registered fx Effect (the fx play
loop drives registered effects only — it does not accept raw ANSI frames), or
render to PNG with the SmartCLI pyte harness.
When to use
- Building a status page / dashboard / control panel that should look designed, not dumped.
- You need boxes, tables, or columns that line up — especially with wide glyphs.
- You want web mental models (box model, flexbox rows, a grid, cards) in a TUI.
- Adding a new reusable terminal widget to a shared catalog.
- Do NOT use for full-screen interactive apps with input loops — that is drive-tui's job. tui-ui produces frames; something else owns the terminal.
Setup
Run from the skill directory skills/tui-ui as a package:
python -m ui widgets # list widgets (--json for machine-readable)
python -m ui demo <name> --width 60 --height 12 # render one widget
python -m ui gallery --width 100 --height 30 # the showcase dashboard "page"
python -m ui demo table --theme synthwave # --theme applies a palette
python -m ui sixel image.png --cols 40 --rows 20 # TRUE-graphics bitmap (sixel)
python -m ui sixel --cols 40 --rows 20 # no image: renders a demo gradient
python -m ui sixel image.png --mode braille # sampling density: half|quad|sextant|braille
python -m ui sixel --probe # does this terminal support sixel?
Beyond sub-cell glyphs, tui-ui can emit true bitmap graphics via Sixel for
terminals that support it (Windows Terminal ≥1.22, xterm, WezTerm, mlterm): the
ui.sixel module encodes any RGB pixel grid — including a SubcellRaster.px
buffer, via raster_to_sixel(raster) — to a DCS escape string
(encode_sixel(pixels) / print_sixel(...)). supports_sixel() runs a DA1 probe
(returns True/False/None-unknown; on Windows it always returns None — there is no
reliable raw-console DA1 round-trip). This is the graphics-protocol escape hatch above
the half/quad/sextant/braille sub-cell rendering; the sub-cell path still works on
every terminal, sixel is the upgrade where available.
Or by path from anywhere (a PEP-366 prelude bootstraps the package):
python skills/tui-ui/ui/cli.py gallery
On Windows set PYTHONIOENCODING=utf-8 (or the CLI auto-reconfigures stdout) so
box/CJK glyphs encode. The CLI renders once and exits — bounded, no loop.
Geometry law: a terminal cell is ~2× taller than wide (ASPECT = 2), so any
isotropic metric on the cell grid must correct y — dist = sqrt(dx² + (dy*2)²)
— or circles render as vertical columns; ui.field bakes this in. The one
exception is SubcellRaster: its sub-cell pixels are screen-square (the
subdivision cancels ASPECT), so raster geometry uses a plain Euclidean metric —
never apply the correction twice.
The box model (ui/box.py)
A Box wraps content in the CSS nesting order margin → border → padding →
content. Borders are cells (1 per present side), padding is the CSS 4-tuple
(top, right, bottom, left), and box-sizing defaults to border-box: the
requested width/height IS the border box, and content = width − gutter where
gutter = padding + border per axis.
from ui import Box
Box(content="hello",
width=24, height=5, # int cells | "auto" | Fr(2)/"2fr" | "50%"
border="rounded", # single | rounded | heavy | double | ascii | none
padding=(0, 1), # int | (v,h) | (t,r,b,l)
margin=0,
title="Title", title_align="left", # left | center | right
align="left", valign="top", # content alignment inside the padding box
fg=(210,216,228), bg="#0e1016", border_fg="#4a5a82")
Box.measure(w, h) -> (w, h) reports the natural outer size; Box.render(w, h) -> Canvas draws it into an exact region. Content taller/wider than the region is
clipped to the content box so it never overwrites the border.
Layout (ui/layout.py)
Containers share the widget protocol (measure / render), so they nest freely.
VStack(children, gap, align, valign)— stack top→bottom; cross axis is width.HStack(children, gap, valign)— flex row left→right;frchildren share width.Grid(cells, cols, rows, col_gap, row_gap)— rows × cols;grid(cells, ncols=3)is the shortcut.Page(child, width, height)— the fixed-size root;page.to_ansi()is your frame.
fr / fractional distribution is the load-bearing algorithm. Never round each
track independently (that drifts ±1). The engine uses Rich's carry-remainder method,
so resolve_tracks(10, [Fr(1),Fr(1),Fr(1)], ...) == [3, 3, 4] exactly and cumulative
offsets never drift. Fixed/auto tracks are measured and subtracted first; the
remainder is shared among fr tracks by weight; overflowing fixed tracks shrink
largest-first to fit.
Compose a "page"
A dashboard is just a tree of boxes and widgets handed to a Page:
from ui import Page, VStack, HStack, Box, Fr, get_theme
from ui.widgets import Banner, Badge, Table, Meter, ProgressBar, Tabs, Tree
t = get_theme("dashboard")
def panel(content, title, **kw):
return Box(content, border="single", title=title, padding=(0,1),
bg=t.bg, fg=t.fg, border_fg=t.border, **kw)
page = Page(
VStack([
Box(Banner("DASH", theme=t), border="rounded", border_fg=t.accent, height=8),
HStack([panel(Meter(theme=t), "Resources"), # auto width
panel(Table(theme=t), "Services", width=Fr(1))], gap=1), # flex fill
panel(ProgressBar(0.73, label="Deploy", theme=t), "Progress", height=3),
], gap=0, bg=t.bg),
width=100, height=30, bg=t.bg)
print(page.to_ansi())
See ui/cli.py:_build_gallery for the full showcase (banner, badge status row, a
two-panel middle region, tabs, and a progress footer). Themes live in
ui/core.py (dashboard, synthwave, forest, mono, amber); each carries
semantic slots (bg fg muted border accent ok warn err) plus gradient stops.
Widget catalog
python -m ui widgets lists them; each has a sample(theme) used by demo/gallery.
| key | what it renders |
|---|---|
panel | Bordered frame with title + word-wrapped body |
table | Auto-sized data table with borders, bold header, status coloring |
card | Composite: title + body + key/value list + badge footer |
progress | Progress bar, 1/8-cell precision (█▉▊▋▌▍▎▏), gradient fill + percent |
meter | Multi-row labelled bar chart (CPU/MEM/DISK style) |
tabs | Tab strip with the active tab underlined + a content pane |
kv | Two-column key/value (definition) list; keys padded, values wrap |
tree | DFS tree with ├──/└──/│ guide glyphs |
rule | Horizontal divider with an optional aligned title |
badge | Inline status pill / chip (ok/warn/err/accent) |
banner | Big FIGlet text (needs pyfiglet; degrades to a bold label) |
Plus 6 shader/raster-backed extras shipped in ui/widgets_ext/ (the effort-replica primitives, a sub-cell chart, and an fzf-style filter pair; also in python -m ui widgets):
| key | what it renders |
|---|---|
gradient_rule | Solid rule filled with a per-cell truecolor gradient |
radial_glow | Localized rounded/pulsing radial glow (background light field) |
slider_track | Thin solid slider rail with a marker + tick labels |
braille_chart | Smooth sub-cell line chart of a data series (braille 2×4 px/cell) |
fuzzy_filter_list | fzf-style fuzzy-filtered list with match highlighting |
preview_pane | Content preview pane (title + line numbers); pairs with the fuzzy list |
Add a widget (the recipe)
Drop a module in ui/widgets_ext/ — registry.load_all() discovers it, no wiring.
# ui/widgets_ext/spark.py
from ui.registry import register
from ui.widgets import Widget
from ui.core import Canvas
@register
class Spark(Widget):
key = "spark" # registry key (python -m ui demo spark)
summary = "Inline sparkline" # shown by `widgets`
def __init__(self, values=(1,3,2,5,4), *, theme=None):
super().__init__(theme)
self.values = list(values)
def measure(self, avail_w, avail_h): # (width_wanted, height_wanted)
return (len(self.values), 1)
def render(self, region_w, region_h): # -> exact-size Canvas
cv = Canvas(region_w, max(1, region_h), bg=self.theme.bg)
bars = "▁▂▃▄▅▆▇█"; hi = max(self.values) or 1
for i, v in enumerate(self.values[:region_w]):
cv.set(i, 0, bars[min(7, v*7//hi)], fg=self.theme.accent, bg=self.theme.bg)
return cv
@classmethod
def sample(cls, theme): # used by demo/gallery
return cls(theme=theme)
Contract for new widgets: measure(avail_w, avail_h) -> (w, h) and
render(region_w, region_h) -> Canvas of exactly that region. (Some historical
built-ins return a taller Canvas and rely on the parent blit to clip it — do
not imitate that.) Set class attrs
width/height (int / Fr / "auto") if a parent stack should size it specially.
Then: python -m ui widgets (it appears) and python -m ui demo spark.
Width & alignment (why columns don't misalign)
The engine never uses len(). ui.core.width(s) returns display cells: CJK /
fullwidth → 2, combining marks → 0, ANSI stripped to 0, and emoji measured the
way pyte/tmux advance the cursor — as a per-codepoint sum: a ZWJ sequence counts
each emoji (👩💻=4), VS16 does not widen its base (♀️=1), and a
regional-indicator flag pair is two wide codepoints (🇯🇵=4).
Canvas.put_text is wide-aware: a double-width glyph occupies its cell
plus a continuation cell that is never serialized, so a CJK char can't shove the
columns behind it. blit heals any wide glyph it cuts at a seam.
tmux safety & rendering to PNG
to_ansi() emits only CSI SGR color runs (\x1b[…m, run-length like fx) and
newlines — no cursor moves, no alt-screen, no scroll region. A frame is therefore
composable and safe to print inside a tmux pane; tmux re-parses it through its own VT
layer identically. If tmux is available on the machine, verify frames in a real
pane; when it is not, verify with pyte (a faithful VT emulator) → PNG via
PIL — the standard no-tmux snapshot method — and always label such captures as
pyte-simulation, not a real-tmux capture (see tools/screenshot/shot.py:RENDER_LABEL).
Run from the repo root; needs pip install pyte pillow:
import sys; sys.path[:0] = ["tools/screenshot", "skills/tui-ui"]
import shot
from ui import get_theme; from ui.cli import _build_gallery
ansi = _build_gallery(get_theme("dashboard"), 100, 30).to_ansi()
screen = shot.render_bytes_to_screen(shot.render_frame_to_bytes(ansi), 100, 30)
shot.screen_to_png(screen, "out.png") # faithful cell-grid render
Knowledge base — look before you build
Before recreating or inventing any effect, consult the SmartCLI knowledge graph at
knowledge/INDEX.md (from the repo root; in a standalone skill install without
the repo, the references/ twins below are the authority) — 95 sourced concept
notes + 27 case studies,
organized around one discipline: pick your lane.
- Replica (reproduce a real, existing UI/animation/screenshot): measure ground truth
first, never head-canon. Start at [[hard-lessons]] (mirrors
references/HARD-LESSONS.md) and the worked case [[effort-selector]] (measured palette/geometry/animation for the/effortpicker) → drive-and-capture, quantify scale + form, extract exact params, build against truth, verify on the real run path. - Creative (design a new widget/effect): compose primitives. Start at [[rendering-model]]
(mirrors
references/RENDERING-MODEL.md, the four-primitive kernel) and ask "which primitives compose this?" before writing a bespoke widget.
Recreating a REAL effect — read this first
Before recreating any effect that already exists (a real CLI's UI, an animation, a
screenshot), read references/HARD-LESSONS.md and follow its 10 rules. It is the
distilled record of a replica that took a dozen wrong iterations because of guessing
instead of measuring. The non-negotiable core:
- Get ground truth first — never approximate from imagination. If the real program
exists, drive it with
smartcli_core.PtySession, capture the actual rendered per-cell bytes/colors, and for animations capture multiple PNG frames and study them. Reverse-engineer exact constants from source when available. - Confirm scale and shape before writing render code — how many rows/cols the effect occupies, 1-D vs 2-D, static vs animated, and how it moves (measure the moving edge across frames, don't guess). A ripple that is really an 8-row rectangle will never be reproduced as a 1-row bar.
- Verify on the REAL run path, never on a self-satisfying preview. Run the script's
own full startup (
python script.py, no monkeypatches), capture stderr, and use SmartCLI to drive your own script and diff its real output against ground truth. A missing import or anisatty()early-return produces a blank/crash the PNG preview won't show. - You have the tools to look — use them. You are an agent CLI with PTY + screen capture + PNG rendering. Don't ask the user what it looks like; go capture it.
Replica smoke workflow
When recreating a screenshot-driven CLI/TUI, do not finish after visual intuition or one
happy-path preview. Create a bounded --once frame mode in the target program, then
render a matrix through tools/screenshot/shot.py or tools/screenshot/cli.py.
Minimum checks for a screenshot replica:
- Cover every visible state in the reference, plus separate animation frames for each distinct animated backdrop or transition shape.
- Render at the reference size and at least two stress sizes, such as
80x24and a wider/taller terminal. - Assert the stream contains truecolor ANSI when color is part of the design, has no
U+FFFD, and includes the key visible labels from the reference. - Inspect the generated PNG contact set manually before handoff; pyte checks catch blanks, clipping, color presence, and mojibake, but not taste, exact spacing, or whether an active color reads like the reference.
- Run one interactive smoke in a real terminal (Windows Terminal, iTerm2, or your platform's terminal) for input semantics, alt-screen restoration, cursor restoration, and resize behavior. Pyte is not a substitute for keyboard/input-loop verification.
For interactive replicas, make Enter and Esc behavior observable: emit the selected
value or use distinct exit status/cancel semantics after leaving the alt screen. Keep
--once non-interactive and deterministic so reports can reproduce the PNG set.
Self-test (bounded, no loop)
python self_test.py renders the 100×30 dashboard once and asserts: 30 rows each
exactly 100 cells (no fr drift), box-drawing glyphs present, truecolor SGR present,
width() edge cases correct, and a CJK table row's vertical bars land on the SAME
columns as an ASCII row (proving wide-char alignment). Exit 0 = pass. It also passes
cleanly at sizes (40,12), (80,24), (120,40), (200,50).
File map
ui/core.py—Canvas,Cell,width(), color/SGR helpers, box-glyph tables,Themes.ui/box.py— the CSS box model (Box,Fr, dim resolution, clipping).ui/layout.py—VStack/HStack/Grid/Page+ carry-remainderfrresolution.ui/widgets.py— the 11 core web-style widgets.ui/widgets_ext/— 6 shipped extras (gradient_rule,radial_glow,slider_track,braille_chart,fuzzy_filter_list,preview_pane) + drop a module here to add your own.ui/registry.py—@register+ folder discovery.ui/cli.py—widgets/demo/gallery(+--width --height --theme).ui/field.py— CellField shader engine (Ripple/RadialGlow/LinearGradient/Plasma+ ASPECT dist).ui/raster.py—SubcellRaster: off-screen pixel buffer downsampled to half/quad/sextant/braille sub-cell glyphs (screen-square pixels — no ASPECT term here).ui/box_junction.py—BoxGridedge algebra: lines deposit N/E/S/W arm weights and the glyph is a pure table lookup, so crossings auto-connect (┼,┿, …).ui/color_model.py— honest color degrade (truecolor → 256 → 16 → mono, real nearest-match) + display-width helpers for CJK/emoji alignment.ui/sixel.py— Sixel encoder: any RGB pixel grid → DCS escape string (encode_sixel/print_sixel,supports_sixel()DA1 probe).self_test.py— bounded render assertions.references/HARD-LESSONS.md— read before any replica: 10 rules from a dozen failed iterations (knowledge twin: [[hard-lessons]]).references/RENDERING-MODEL.md— first-principles: cell grid, shader fields, sub-cell, box algebra (knowledge twin: [[rendering-model]]).examples/effort_selector.py— worked replica of a real /effort-style selector (ground-truth-driven; measured constants: [[effort-selector]]).knowledge/INDEX.md(repo root; absent in standalone skill installs — use thereferences/twins instead) — the knowledge graph: look here before building (replica vs creative lanes).
What ships with it: 27 files
249.4 KB alongside SKILL.md, 24 of them executable
examples/
- effort_selector.pyruns22.1 KB
references/
- effort-replica-spec.md11.8 KB
- HARD-LESSONS.md7.5 KB
- RENDERING-MODEL.md5.4 KB
ui/
- box_junction.pyruns13.5 KB
- box.pyruns9.2 KB
- cli.pyruns8.7 KB
- color_model.pyruns3.6 KB
- core.pyruns20.7 KB
- field.pyruns19.7 KB
- __init__.pyruns1.4 KB
- layout.pyruns11.1 KB
- __main__.pyruns183 B
- raster.pyruns27.9 KB
- registry.pyruns2.7 KB
- sixel.pyruns9.2 KB
- widgets_ext/braille_chart.pyruns6.7 KB
- widgets_ext/fuzzy_filter_list.pyruns5.0 KB
- widgets_ext/gradient_rule.pyruns3.5 KB
- widgets_ext/__init__.pyruns207 B
- widgets_ext/preview_pane.pyruns3.1 KB
- widgets_ext/radial_glow.pyruns8.8 KB
- widgets_ext/slider_track.pyruns7.7 KB
- widgets.pyruns24.3 KB
- _selftest_effort_widgets.pyruns4.9 KB
- self_test.pyruns5.7 KB
- _shot_effort_widgets.pyruns4.7 KB
Gives 0 of the 12 instructions most design frontend skills give
Counted across 1,179 of the 2,086 authors here whose files we hold, read 2026-09-06
- Commit to a bold aesthetic directionin 31 of 1179, across 24 files
- Prefer component composition over inheritancein 28 of 1179, across 14 files
- Animate only transform and opacity propertiesin 27 of 1179, across 22 files
- Memoize expensive computations with useMemoin 26 of 1179, across 13 files
- Use semantic HTML elementsin 24 of 1179, across 23 files
- Virtualize long lists for performancein 21 of 1179, across 10 files
- Use CSS variables for design tokensin 20 of 1179, across 14 files
- Implement loading, empty, and error statesin 20 of 1179
- Lazy load heavy components with Suspensein 19 of 1179, across 8 files
- Respect prefers-reduced-motion media queriesin 18 of 1179, across 10 files
- Prioritize CSS-only animations for HTMLin 18 of 1179, across 16 files
- Use compound components for related UI elementsin 18 of 1179, across 7 files
Said here and by no other author read
- compose a tree of renderables for the engine
- use web mental models like box model and flexbox
- measure ground truth before recreating existing effects
- verify frames in a real tmux pane if available
- use pyte and PIL to render frames to PNG
- run the self test script to verify layout
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.