Home /Modules/sleela-terminal/UI-PRINCIPLES.md

UI-PRINCIPLES.md

sleela-terminal/UI-PRINCIPLES.md · 166 line(s) · markdown

SleelaTerminal™ UI Principles

A short, enforceable set of rules for the look and feel of the SleelaTerminal™ graphical terminal (SleelaTerminal, GTK 4 + VTE). The goal is a clean, calm, legible terminal where the shell content is the hero and the chrome is a quiet, consistent frame.

These principles describe presentation intent. They do not change shell behaviour, add network/data behaviour, or alter the configuration schema.

1. The terminal is the hero

The VTE terminal is the primary, centered workspace. Chrome (title bar, footer, popovers) is a quiet frame around it. Chrome must never compete with terminal content for attention: no blinking, flashing, or attention-grabbing motion. Controls appear on demand (popovers / right-click), not as permanent panels.

The one sanctioned exception is the title-bar lightbar (the "light bar"): a living green seam along the bottom of the title bar that replaces the old static border. The whole bar is green — a lit fluorescent tube (mid-emerald base with an even energised wash) hosting a single pulse of light that is logarithmically centred: the lit glow is seeded at the centre and grows outward in width on a logarithmic curve, breathing at a slow heartbeat. The widening is the thing observed. At the peak of its expansion the glow fades back to the original green and the cycle restarts, so the only motion the eye sees is the centred glow getting wider and softer, never a travelling spark. Every knob of the effect (base/glow green, pulse frequency in Hz, start/peak width, the logarithmic growth shape, peak brightness) is a conserved named constant in the lightbar configuration namespace in sleelaterminal-gui.cpp, so it can be addressed as a single artistic surface. It is allowed because it is ambient — low-contrast, slow, edge-only, and carrying no information the user must track — so it signals "alive" without pulling the eye from the terminal. Any motion in the chrome must clear that same bar.

2. One palette, one source of truth

All colours come from a single named palette defined once at the top of the CSS (as CSS custom properties / @define-color). No raw hex values are scattered through individual selectors. Changing the theme means editing one block.

The window chrome retains the project's dark rich-purple family, while the terminal text pane and command-result surfaces use a separate neutral, high-contrast reading palette:

TokenValueUse
--sl-bg#15101cwindow chrome background
--sl-surface#21112fpopovers, dialogs, raised surfaces
--sl-surface-hi#321a4dgradient top / hover surface
--sl-chrome#24103ffooter base / raised chrome
--sl-titlebar-bg#4b4b4btitle-bar fill — the same flat gray as the terminal text area (--sl-output-bg)
--sl-border#7f56aa1px separators and surface borders
--sl-fg#ffffffchrome text / controls
--sl-fg-dimrgba(255,255,255,.70)secondary / note text
--sl-accent#9d6cfffocus ring, suggested action

The GTK workspace uses #fcfcfc (RGB 252, 252, 252). The interactive VTE terminal surface uses charcoal #4b4b4b with near-white #f2f2f2 text. Keep this three-colour hierarchy consistent: near-white workspace, dark terminal surface, light readable terminal text. The purple/black palette belongs to the surrounding window chrome only.

Command summary row: after an interactive command is submitted, slsh prints a muted warm-brown summary strip containing the entered command and local date/time. The command's output begins on the following line. This is ANSI background applied to the summary text cells, not a separate GTK panel. The terminal/workspace colours remain unchanged. Non-interactive scripts do not receive these presentation rows.

Implementation boundary: VTE still presents an ongoing interactive PTY stream, not discrete command-result widgets. The summary strip does not yet create a separate rounded output panel that appears only when output exists. Do not describe that larger output-view architecture as implemented.

3. Restraint over effects

4. Consistent spacing

Use a 4px spacing scale: 4, 8, 12, 16. Container padding is 12. Related controls are spaced 6. Section gaps are 12. Do not invent one-off margins (no 14, 22, 5). Popovers and dialogs share the same inner padding (12).

5. Type hierarchy, minimal weights

6. Calm status, no motion

The footer presents static status: brand, a separator, one status string, the version. It does not rotate or scroll text in the resting state. (A ticker, if ever desired, is opt-in via configuration — off by default — because moving text competes with terminal output; see SETTINGS.md.)

7. Clear, honest affordances

8. Accessibility baseline

9. Correctness of the stylesheet

10. Maintenance rule

When the GUI's look changes, update the palette block (not individual selectors), keep this document in sync, and rebuild make gui to confirm the stylesheet still parses. If a change adds motion, a new colour, or a new spacing value, it must either fit these principles or update them deliberately.

— SleelaTerminal™ · MEARVK LLC

11. File browsing and ls output

The main workspace remains near-white (#FCFCFC); the interactive terminal uses charcoal (#4B4B4B) with light text (#F2F2F2). The custom ls builtin and per-file tiles have been removed. The shell resolves ls through the normal external-command PATH lookup, so the platform's standard ls provides its native output format and full flag set (including -l and -la). Command flags are preserved as argv entries, and redirected output and pipelines remain free of GUI styling sequences.

The command summary strip is separate from command output: it shows the command text and local timestamp, then the result follows on the next line. It does not alter command arguments, stdout bytes, or redirection contents.

12. Independent terminal tabs

The main terminal workspace supports multiple tabs in one window. Each tab owns its own VTE widget, PTY, shell process, scrollback, and terminal state; commands and working-directory changes in one tab must not affect another. The first and subsequent tabs share the application frame, palette, settings, and footer. A plus control creates a tab; each tab has its own close control. Keyboard shortcuts: Ctrl+Shift+T creates a tab, Ctrl+Shift+W closes the current tab, Ctrl+Tab / Ctrl+Page Down advances, and Ctrl+Shift+Tab / Ctrl+Page Up goes back. Closing a shell tab must not terminate other tabs; closing the final tab closes the application. The existing near-white workspace and charcoal terminal surface are unchanged.