tui-standards
Skill4 starsChanged 58 days agoMITView on GitHub
TUI component standards — shared primitives in ui/shared/_components.py, the mandatory Panel page structure, themes, buttons, scrollbars, viewport math. Use when creating or modifying any TUI screen, any _build_*_screen function, or code under src/yeaboi/ui/.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-and-stateSkill
- babysit-prsSkill
- ci-and-releaseSkill
- development-automationSkill
- loggingSkill
- mode-blueprintsSkill
- pr-feedbackSkill
- project-mapSkill
- web-frontendSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
All TUI screens MUST use the shared component system in src/yeaboi/ui/shared/_components.py.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
TUI Component Standards
All TUI screens MUST use the shared component system in src/yeaboi/ui/shared/_components.py. Do NOT duplicate rendering logic.
Shared Primitives (use these, don't rewrite)
| Component | Function | Purpose |
Theme | ANALYSIS_THEME, PLANNING_THEME, USAGE_THEME, SETTINGS_THEME | Colour palette per mode (incl. bg page tint) |
| Page panel | build_page_panel(content, theme=, height=) | The full-screen root Panel every page returns |
| Buttons | build_action_buttons(actions, selected) | Consistent button row (Accept/Edit/Export/Back etc.) |
| Scrollbar | build_scrollbar(viewport_h, total, offset, max_scroll) | Right-side scroll indicator |
| Progress | build_progress_dots(stages, current, theme=) | Stage indicator (● ● ○ ○ ○) |
| Viewport | calc_viewport(height, header_h=, action_h=) | Viewport height calculation |
| Titles | planning_title(), analysis_title(), usage_title(), settings_title() | ASCII art headers |
| Popup | build_popup(message, width=, border_style=) | Confirmation dialogs |
| Badge | build_badge(label, rgb=BETA_RGB, dim=) | Inverse-video status chip (BETA, COMING SOON). Takes an rgb tuple, not a colour string — dim does arithmetic on the channels, and COLOR_RGB only knows the mode accents. Never draw a chip with box glyphs: the mode-card click hit-testing finds title rows by scanning for █▀▄ |
| Padding | PAD constant | Left indent for visual balance |
Beta modes. A mode whose output isn't verified yet keeps "available": True
in _MODE_CARDS (that flag gates Enter, the click handler and the welcome
screen's g jump key — flipping it removes the feature rather than labelling
it) and adds "badge": BETA_LABEL. Three markers must move together, and
test_beta_surfaces.py::TestBetaMarkersAgree enforces it: the card badge, a
_BETA_MODES entry in ui/shared/_beta_notice.py (the one-time entry notice),
and FeatureTip(is_beta=True). Where both could render, BETA beats NEW.
Page Structure (every _build_*_screen function MUST follow)
build_page_panel(content, theme=<MODE_THEME>, height=height) # NEVER a raw full-screen Panel(...)
├── Text("") # blank
├── title # ASCII art from *_title()
├── Text("") # blank
├── subtitle / progress dots # context line
├── Text("") # blank
├── viewport_renderable # scrollable content (with optional scrollbar)
├── Text("") # blank
├── btn_top # from build_action_buttons()
├── btn_mid #
└── btn_bot #Rules
- DRY — Never inline button rendering, scrollbar math, or viewport calculations. Always use shared functions.
- Themes — Never hardcode colour values (
"rgb(100,180,100)"). Usetheme.accent,theme.muted, etc. from the appropriate Theme constant. - New pages — Adding a new mode/page requires: a Theme constant (including a dark
bgtint of the accent hue), a*_title()function, a colour entry inCOLOR_RGB, an entry in_MODE_CARDS(if it's a main menu item), and aFeatureTipinui/shared/_tips.pykeyed by the capability (withmode_key= the card key so the welcome-screengkey jumps in;is_new=Truefor a release or two), and — if the mode records runs — a saved-sessions hub registered inSAVED_SESSION_HUBS(ui/mode_select/__init__.py), which is what the card lands on.TestTipsandTestSavedSessionsenforce this. - Consistency — All pages use the same Panel structure (title → subtitle → viewport → buttons). No exceptions.
- Page background — Every page paints its own background so all users see the same TUI regardless of terminal theme.
build_page_panelappliestheme.bg(a dark tint of the mode accent;NEUTRAL_BGfor home/setup/settings pages) as the Panel style, and Rich cascades it onto every child segment — content rows, spacers, scroll filler, padding. Never return a raw full-screenPanelfrom a builder;tests/unit/test_screen_backgrounds.pyfails the build if one appears.MusicLive._stampback-fillsNEUTRAL_BGon any unstyled Panel as a safety net, and non-Panel surfaces (screensaver, splash) set their ownon NEUTRAL_BGstyle. Keep tints dark (channel values ≤ 40) — foreground styles assume dark backgrounds. - Saved sessions — A mode that records runs MUST land on a saved-sessions hub, not on its own live page: a finished run the user cannot get back to is a run they lost. Build it with
_run_mode_hub(...)(ui/mode_select/__init__.py) — injectload_runs→RunSummarys,make_detail(oropen_snapshotwhen the snapshot needs its own buttons),files_export,get_document,delete_run,run_new— and register the card key inSAVED_SESSION_HUBS. Render the snapshot through the mode's own screen builder in a snapshot mode, so a saved run looks like the live view rather than flat text.tests/unit/test_surface_parity.py::TestSavedSessionsfails the build for a card with neither a hub nor aSAVED_SESSIONS_EXEMPTreason. - Scrollbar — Content that can overflow MUST use
build_scrollbar(). Usealways_show=Truefor pages where the track should always be visible. - Buttons — Register new button labels in
_BTN_COLORSdict in_components.pywith accent/grey colour tuples. - No
_PADaliases — ImportPADdirectly fromyeaboi.ui.shared._components. Legacy_PAD = PADaliases exist but should not be added to new files. - Never log in per-frame code —
_build_*_screenbuilders and render paths run every frame (~60 fps);logger.infobelongs in key-handling branches of runner loops and one-shot functions only (see theloggingskill).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

