Home /Modules/user-interface/UI-PRINCIPLES.md

UI-PRINCIPLES.md

user-interface/UI-PRINCIPLES.md · 91 line(s) · markdown

SleelaUI™ UI Principles

A short, enforceable set of rules for the look and feel of the SleelaUI™ toolkit. The goal is a clean, calm, legible interface where content is the hero and the chrome is a quiet frame — the same discipline the SleelaTerminal™ GUI follows, applied to a general widget set. These describe presentation intent; they do not change the widget API or behaviour.

1. Content is the hero

Widgets serve the content. Chrome — header bars, separators, borders — is a quiet frame, never attention-grabbing. No blinking, flashing, or gratuitous motion. Controls read as controls; labels read as labels.

2. One palette, one source of truth

All colours come from a single named palette: the SLUITheme struct, resolved once per window. No raw colours are scattered through individual widgets. Changing the theme means editing one struct (or loading one .conf). The default palette is Slick Black:

RoleSlick BlackUse
bg#0d0d0fwindow floor (matte near-black)
surface#161619panels, cards, entries
surface_hi#202125hovered surface / gradient top
chrome#101013header-bar strip
border#2a2b301px hairline separators
fg#ffffffprimary text / glyphs
fg_dimwhite @ .70secondary / disabled text
accent#5e9cfffocus ring, suggested action, selection
danger#e54b4bdestructive action / close-hover

The window floor is a hair above pure black so the rasterizer's antialiasing has somewhere to blend; surfaces step up in small, even increments so panels read without hard borders.

3. Restraint over effects

4. Consistent spacing

Use the 4px scale: 4, 8, 12, 16, 20. theme.unit is 4. Container padding is 12–20; related controls are spaced 8; section gaps 12. Do not invent one-off margins.

5. Type hierarchy, minimal weights

6. Clear, honest affordances

7. Accessibility baseline

8. Identical on every platform

The look is defined by the portable core and the software rasterizer, so it is pixel-identical on Windows, macOS, and Linux/Unix. A backend never styles anything — it only shows the pixels the core produced and reports input. This is the deliberate difference from toolkits that inherit three native themes.

9. Maintenance rule

When the look changes, update the palette (the preset in src/slui_theme.cpp) — not individual widgets — keep this document in sync, and run make smoke to confirm the core still builds and renders. If a change adds motion, a new colour, or a new spacing value, it must either fit these principles or update them deliberately.

— SleelaUI™ · MEARVK LLC