w0rxbend/tui-design-systems

TUI-Designsysteme (Ratatui)

Regeln für neue oder überarbeitete Ratatui-TUI-Visuals, ohne das Interaktionsmodell zu brechen. Für die Rust-Terminal-Dashboards des Benutzers; mit repo-lokalen App-Anweisungen kombinieren.

Wann verwenden

• Neue Ratatui-Dashboard-Visualisierungsebene (Themes, Panels, Badges, Meter, Tabs).
• Überarbeitung/Neugestaltung eines bestehenden Ratatui-TUI, besonders mit mehreren Themes, Live-Theme-Auswahl, Maus-Hit-Testing oder deterministischem Screenshot-Gate in CI.

Token-Architektur

• Paletten flach, konstant und wenige halten: eine semantische Rollen-Struktur pro Theme, per Pointer getauscht. Jede geschichtete oder gemischte Farbe als Token von diesen Rollen mit einem RGB blend() ableiten: surface und surface_hi (Panel-, Overlay-Füllungen), track (leeres Balkenende), fade (Farbe zum Hintergrund hin abgedunkelt), gradient (Akzentverlauf), on_color (lesbarer Badge-Text, per Luminanz gewählt). Eine neue Palette gestaltet dann jedes Komponent auf einmal um – so, wie es ein Live-Theme-Picker benötigt.
• Widgets verwenden niemals Literal-Color, sondern nur Theme-Tokens.
• blend() gegen nicht-RGB-Endpunkte schützen: ANSI-Farben haben keine Kanäle, daher zum näheren Endpunkt schnappen, keinen erfinden.

Hintergrundlose Themes

• Ein Theme mit Color::Reset-Hintergrund (Mono/TTY-Palette) muss jede Füllung degradieren: Oberflächen fallen auf Reset zurück, Badges werden zu geklammertem farbigem Text, leere Balkenenden verwenden Rahmenfarbe, nicht abgeleitetes track (das ist Reset und rendert als Terminal-Standard-Vordergrund). Teste, dass es nur Reset und Auswahl-Highlight malt.

Hintergrundintegrität

• Jede Ansicht × Overlay mit einem Zellbuffer-Test durchgehen: Jeder Zellenhintergrund muss in der vom Theme bereitgestellten Whitelist (is_background-Tokenliste) sein, keine hartcodierte Farbliste. Eine hartcodierte Liste muss bei jedem neuen Token bearbeitet werden und wird vergessen.
• Clear setzt Zellen zurück, ohne neu zu malen; was danach zeichnet, muss den Hintergrund neu stylen. Overlay-Füllungen mit erhöhter surface auffüllen, sodass sie über Panels schweben.
• ratatuis Chart malt den Plotbereich über Canvas, dessen Hintergrund standardmäßig auf Color::Reset gesetzt ist. In getöntem Panel den Chart-Hintergrund auf die Panel-Füllung setzen, nicht auf die Seite: Seitenfarbe innerhalb einer oberflächenfarbenen Karte ist dasselbe Loch, eine Ebene höher.

Layout-gekoppeltes Hit-Testing

• Wenn Maus-Hit-Testing das gezeichnete Layout spiegelt (Tab-Leisten, segmentierte Balken, Statusfelder), ändere Zeichnung und Spiegel-Mathematik im selben Edit. Bevorzuge render-getriebene Tests, die jedes Label anhand der gezeichneten Spalte lokalisieren; handgeschriebene Rechteck-Assertions bestehen, während das echte Layout das Widget woanders platziert.
• Ein hinzugefügtes oder verbreitertes List-Highlight-Symbol verschiebt den Text jeder Zeile. Klickbare Zeilenbereiche müssen vollbreit oder neu berechnet sein, um zu passen.

Glyphen

• Sub-Zellen-Meter-Präzision verwendet Achtel-Blöcke (U+258F..U+2589), Block-Elemente: nur Unicode-Pfad; ASCII-Fallback füllt ganze Zellen. Auch Braille-Diagramme und Sparklines: ASCII-Ersatz bereitstellen, keine Box-Zeichen in den --ascii-Modus durchsickern lassen.
• Symbole in ausgerichteten Spalten müssen single-width BMP-Symbole sein. Emojis sind double-width und verschieben still alle späteren Spalten in der Zeile.

Verifikation

• Neuentwurf: erst Stile ändern, dann Text. Rendering-Tests assertieren Textinhalt, daher bleiben unberührte Strings die Test-Suite grün, während sich das Aussehen ändert.
• Visuelles Gate: deterministischer Screenshot-Generator des Projekts (fester Frame-Zähler, keine Echtzeit-Uhr, kein RNG). Text-Dump-Modus ist die schnellste Layout-Überprüfung. Generierte Bilder mit Quellcode-Änderung committen, damit der CI-No-Drift-Check besteht.
• Hintergründe im Zellbuffer prüfen, nicht im gerenderten Bild: Der Bildschreiber, der Color::Reset zum Theme-Hintergrund auflöst, versteckt genau die Löcher, die der Buffer-Sweep aufdeckt.
• Frame-Zähler-gesteuerte Animation (Pulse, Blinken) deterministisch halten für reproduzierbare Screenshots.