agentleFS
yeaboi-aiyeaboi-ai/yeaboi.ai/.agents/skills/tui-standards/SKILL.md

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/.

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
  1. Very specific:

    All TUI screens MUST use the shared component system in src/yeaboi/ui/shared/_components.py.

    line 8

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

ComponentFunctionPurpose
ThemeANALYSIS_THEME, PLANNING_THEME, USAGE_THEME, SETTINGS_THEMEColour palette per mode (incl. bg page tint)
Page panelbuild_page_panel(content, theme=, height=)The full-screen root Panel every page returns
Buttonsbuild_action_buttons(actions, selected)Consistent button row (Accept/Edit/Export/Back etc.)
Scrollbarbuild_scrollbar(viewport_h, total, offset, max_scroll)Right-side scroll indicator
Progressbuild_progress_dots(stages, current, theme=)Stage indicator (● ● ○ ○ ○)
Viewportcalc_viewport(height, header_h=, action_h=)Viewport height calculation
Titlesplanning_title(), analysis_title(), usage_title(), settings_title()ASCII art headers
Popupbuild_popup(message, width=, border_style=)Confirmation dialogs
Badgebuild_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 █▀▄
PaddingPAD constantLeft 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

  1. DRY — Never inline button rendering, scrollbar math, or viewport calculations. Always use shared functions.
  2. Themes — Never hardcode colour values ("rgb(100,180,100)"). Use theme.accent, theme.muted, etc. from the appropriate Theme constant.
  3. New pages — Adding a new mode/page requires: a Theme constant (including a dark bg tint of the accent hue), a *_title() function, a colour entry in COLOR_RGB, an entry in _MODE_CARDS (if it's a main menu item), and a FeatureTip in ui/shared/_tips.py keyed by the capability (with mode_key = the card key so the welcome-screen g key jumps in; is_new=True for a release or two), and — if the mode records runs — a saved-sessions hub registered in SAVED_SESSION_HUBS (ui/mode_select/__init__.py), which is what the card lands on. TestTips and TestSavedSessions enforce this.
  4. Consistency — All pages use the same Panel structure (title → subtitle → viewport → buttons). No exceptions.
  5. Page background — Every page paints its own background so all users see the same TUI regardless of terminal theme. build_page_panel applies theme.bg (a dark tint of the mode accent; NEUTRAL_BG for 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-screen Panel from a builder; tests/unit/test_screen_backgrounds.py fails the build if one appears. MusicLive._stamp back-fills NEUTRAL_BG on any unstyled Panel as a safety net, and non-Panel surfaces (screensaver, splash) set their own on NEUTRAL_BG style. Keep tints dark (channel values ≤ 40) — foreground styles assume dark backgrounds.
  6. 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) — inject load_runs → RunSummarys, make_detail (or open_snapshot when the snapshot needs its own buttons), files_export, get_document, delete_run, run_new — and register the card key in SAVED_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::TestSavedSessions fails the build for a card with neither a hub nor a SAVED_SESSIONS_EXEMPT reason.
  7. Scrollbar — Content that can overflow MUST use build_scrollbar(). Use always_show=True for pages where the track should always be visible.
  8. Buttons — Register new button labels in _BTN_COLORS dict in _components.py with accent/grey colour tuples.
  9. No _PAD aliases — Import PAD directly from yeaboi.ui.shared._components. Legacy _PAD = PAD aliases exist but should not be added to new files.
  10. Never log in per-frame code — _build_*_screen builders and render paths run every frame (~60 fps); logger.info belongs in key-handling branches of runner loops and one-shot functions only (see the logging skill).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.