agentsclimarketplace

Tui ui

Skill dwgx/SmartCLI/skills/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

Install
npx -y skills add dwgx/SmartCLI --skill tui-ui

Assembled 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; fr children 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.

keywhat it renders
panelBordered frame with title + word-wrapped body
tableAuto-sized data table with borders, bold header, status coloring
cardComposite: title + body + key/value list + badge footer
progressProgress bar, 1/8-cell precision (█▉▊▋▌▍▎▏), gradient fill + percent
meterMulti-row labelled bar chart (CPU/MEM/DISK style)
tabsTab strip with the active tab underlined + a content pane
kvTwo-column key/value (definition) list; keys padded, values wrap
treeDFS tree with ├──/└──/│ guide glyphs
ruleHorizontal divider with an optional aligned title
badgeInline status pill / chip (ok/warn/err/accent)
bannerBig 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):

keywhat it renders
gradient_ruleSolid rule filled with a per-cell truecolor gradient
radial_glowLocalized rounded/pulsing radial glow (background light field)
slider_trackThin solid slider rail with a marker + tick labels
braille_chartSmooth sub-cell line chart of a data series (braille 2×4 px/cell)
fuzzy_filter_listfzf-style fuzzy-filtered list with match highlighting
preview_paneContent 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 /effort picker) → 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:

  1. 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.
  2. 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.
  3. 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 an isatty() early-return produces a blank/crash the PNG preview won't show.
  4. 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 80x24 and 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-remainder fr resolution.
  • 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 — BoxGrid edge 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 the references/ 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/

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.

Keep looking

Skills are one crate of 611,919. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.