This document records the planned public shell component architecture.
It is a decision record for future implementation work. It does not require the current shell/ files to already match every decision.
Planned public shell components:
shell/colors.sh
shell/color-wash.sh
shell/terminal.sh
shell/terminal-text.sh
shell/loaders.sh
shell/output.sh
shell/text-effects.sh
shell/selector-interactive.sh
shell/selector-numbered.sh
shell/headers.sh
shell/colors.sh owns the public color palette for shell output.
It should provide:
- canonical hex palette tokens
- calculated dim hex palette tokens
- HEX-to-ANSI foreground conversion
- HEX-to-ANSI background conversion for previews
- generated shell truecolor ANSI output
- terminal-ready shell variables for scripts and prompts
- semantic color aliases
- wash palette arrays
NO_COLORopt-outFORCE_COLORoverride for controlled non-TTY color output- non-TTY fallback
Hex color tokens are the canonical color source of truth. Shell ANSI and truecolor output should be generated from those tokens.
After sourcing shell/colors.sh, scripts and prompts should be able to use convenient terminal-ready variables such as SUCCESS, WARNING, ERROR, TEXT_DIM, RESET, ACID_BLUE, GIT_BRANCH, RED, and CYAN. Full-strength colors use names such as SUCCESS; calculated dimmed colors use names such as SUCCESS_DIM.
Classic variables such as GREEN, CYAN, WHITE, and BLACK are part of the public shell API again, but they are explicit truecolor values generated from *_HEX tokens. They are not terminal ANSI slot colors.
Do not maintain separate manual ANSI and tput color palettes. Use tput mainly for terminal control behavior, not the canonical color palette.
shell/color-wash.sh owns the shared terminal color-wash primitive.
It depends on shell/colors.sh for palette data, including wash palette arrays and solid color tokens. It should stay reusable shell UI infrastructure, not application-specific animation code.
It honors the same NO_COLOR / FORCE_COLOR policy as shell/colors.sh: plain output when color is disabled or stdout is not a TTY, with FORCE_COLOR reserved for controlled non-TTY rendering.
shell/terminal.sh owns terminal control primitives.
It should provide:
- cursor hide/show helpers
- clear-line helpers
- terminal capability checks
- cleanup/trap primitives
Terminal cleanup should be reusable by loaders, selectors, and any shell UI that temporarily changes terminal state.
shell/terminal-text.sh owns ANSI-aware visible-width and padding helpers for colored terminal output.
It should provide:
- ANSI escape stripping
- visible string length helpers
- visible-width-aware padding helpers
- padded label/value output helpers
These helpers should stay separate from shell/text-effects.sh, which owns animation rather than terminal text layout.
shell/loaders.sh owns spinner and loader behavior.
It should provide:
- spinner frame sets
- start/stop lifecycle helpers
- cursor restoration
- clean completion output
Loader behavior should be safe to stop repeatedly and should restore terminal state on normal completion, cancellation, and interrupt when practical.
shell/output.sh owns common operator-facing output helpers.
It should provide:
- status, success, warning, and error lines
- wrapped paragraph output
- muted metadata output
- key/value output
- reset-safe colored output
Output helpers should pair color with clear text and should not rely on color alone for critical state.
shell/text-effects.sh owns optional text animation.
It should provide:
- typewriter/string animation
- animated wrapped text
- easing animation
Easing animation is intentionally part of the desired shell UI voice, but it must be optional or safely disableable. Any dependency-heavy animation should degrade cleanly when required commands or terminal capabilities are unavailable.
shell/selector-interactive.sh owns richer interactive selector behavior.
It should provide:
- keyboard-driven selection
- arrow-key navigation
- Enter confirmation
- q, Q, and Escape cancellation
- predictable stdout and status behavior
- explicit cancel handling
- interrupt handling
Interactive selectors should return a predictable selected index or value, return success when a selection is made, return non-zero on cancel, and return interrupt status when interrupted.
shell/selector-numbered.sh owns simpler numbered-choice selector behavior.
It should provide:
- numbered option display
- typed numeric selection
- selected value output on stdout
- non-zero status for invalid or cancelled input
Use this helper when arrow-key navigation would be unnecessary or when a plain numbered prompt is easier to script, test, or explain.
shell/headers.sh owns graphical and script header helpers.
It should stay focused on generating or validating the visual header shapes defined by the script header standard.
Do not add shell/formatting.sh yet.
Full table helpers are deferred for now. Add shell/formatting.sh later only if layout primitives such as tables, boxes, rules, columns, or section dividers outgrow shell/output.sh.
Source-only shell libraries should not have shebangs.
Source-only shell libraries should keep source guards so direct execution fails clearly.
Runnable executable scripts should have /usr/bin/env shebangs.
Public shell variables may need targeted ShellCheck SC2034 suppressions when they are intended sourced-library API.
Sourced shell components are not executable scripts and should not claim to be run directly.
They are still documented source files.
Use top-of-file documentation adapted to the component type:
- include a graphical header when appropriate
- put a
# description:line immediately after the graphical header - add a short introductory comment block explaining how the file is loaded or sourced
- state the component boundary when relevant, such as aliases-only, functions-only, colors-only, or loaders-only
- document platform guards before platform-specific commands or settings
- use clear, useful, single-# section comments consistent with
docs/comments-and-descriptions.md
Platform-specific sourced components should guard platform-specific commands before they run. The comment near the guard should explain the operating-system or shell assumption when it is not obvious.
Files under private/source-samples/ may inform mechanics and design direction.
Do not copy private demo content, screenshots, transcripts, hostnames, usernames, private paths, IP addresses, lyrics, project-specific labels, or analysis prose into public shell libraries or docs.
Extract reusable mechanics only.
Recommended implementation order:
- Add terminal control helpers.
- Refactor shell color tokens.
- Add shell output helpers.
- Harden loader lifecycle.
- Add or refine text effects with optional easing.
- Refine selector behavior.
- Revisit formatting and table helpers later.