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:
| Token | Value | Use |
|---|---|---|
--sl-bg | #15101c | window chrome background |
--sl-surface | #21112f | popovers, dialogs, raised surfaces |
--sl-surface-hi | #321a4d | gradient top / hover surface |
--sl-chrome | #24103f | footer base / raised chrome |
--sl-titlebar-bg | #4b4b4b | title-bar fill — the same flat gray as the terminal text area (--sl-output-bg) |
--sl-border | #7f56aa | 1px separators and surface borders |
--sl-fg | #ffffff | chrome text / controls |
--sl-fg-dim | rgba(255,255,255,.70) | secondary / note text |
--sl-accent | #9d6cff | focus 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
- At most a 1px border for separation; prefer a hairline border or a single
subtle gradient over stacked
box-shadow+inset+ glow. - No
-gtk-icon-shadowglows on controls. Legibility comes from contrast, not halos. - Hover/active states are a small background-opacity step (e.g. `.08 → .16 → .24`), nothing more.
- Transitions, if any, are a single short
120msease on background/opacity.
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
- Terminal text: the user-configured monospace font.
- Chrome text: the system UI font, two weights only —
600for labels,800for the brand/section headings. Avoid a third weight. - Secondary/explanatory text uses
--sl-fg-dimat.9em, never a new colour. - Avoid letter-spacing tricks except the single brand label.
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
- Clickable things look clickable (a surface tint + hover step); non-interactive labels do not.
- The one
suggested-actionbutton per dialog uses--sl-accent; everything else is a neutral surface button. Never two competing primary buttons. - Focus is always visible: a
--sl-accentfocus ring on keyboard focus.
8. Accessibility baseline
- Body/control text on its background meets at least WCAG AA contrast (≈4.5:1).
White (
#ffffff) on the purple chrome and near-black terminal clears this; dim text is reserved for non-essential notes only. - Nothing is conveyed by colour alone; icons carry tooltips and text labels.
- Hit targets are at least
32pxtall.
9. Correctness of the stylesheet
- The GTK CSS lives in a C++ raw string literal
R"CSS( … )CSS". Inside it, real newlines are literal — never write the two characters\n, which GTK's CSS parser rejects and which silently drops the rest of a rule. - Keep selectors flat and class-scoped (
popover.sleela-settings …) so styles don't leak into unrelated widgets.
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.