w0rxbend/tui-design-systems

Systèmes de design TUI (Ratatui)

Règles pour les nouvelles ou refontes complètes des visuels d'une TUI Ratatui sans casser le modèle d'interaction. Pour les tableaux de bord terminaux Rust de cet utilisateur ; à associer aux instructions locales de l'application.

Quand l'utiliser

• Nouvelle couche visuelle pour un tableau de bord Ratatui (thèmes, panneaux, badges, jauges, onglets).
• Refonte/restyling d'une TUI Ratatui existante, surtout si elle comporte plusieurs thèmes, un sélecteur de thème en direct, un hit-testing souris ou une porte de capture d'écran déterministe dans l'intégration continue (CI).

Architecture des jetons

• Maintenez les palettes plates, constantes et peu nombreuses : une structure de rôles sémantiques par thème, échangée par pointeur. Déduisez chaque couleur superposée ou mélangée en tant que jeton à partir de ces rôles via une seule fonction blend() RGB : surface et surface_hi (remplissages de panneaux et de superpositions), track (extrémité vide d'une barre), fade (couleur atténuée vers l'arrière-plan), gradient (bande d'accent), on_color (texte de badge lisible, choisi par luminance). Une nouvelle palette restyle alors tous les composants d'un coup, comme le fait un sélecteur de thème en direct.
• Les widgets ne doivent jamais nommer de Color littérale, uniquement des jetons de thème.
• Protégez blend() contre les extrémités non RGB : les couleurs ANSI n'ont pas de canaux, donc accrochez-vous à l'extrémité la plus proche, n'en inventez pas.

Thèmes sans arrière-plan

• Un thème avec un arrière-plan Color::Reset (palette mono/TTY) doit dégrader tous les remplissages : les surfaces tombent à Reset, les badges deviennent du texte coloré entre crochets, les extrémités vides des barres utilisent la couleur de bordure, et non le track dérivé (qui serait Reset, affiché comme la couleur par défaut du terminal). Testez qu'il ne peint que Reset et la surbrillance de sélection.

Intégrité de l'arrière-plan

• Balayez chaque vue × superposition avec un test de tampon de cellules : l'arrière-plan de chaque cellule doit être dans une liste blanche fournie par le thème (liste de jetons is_background), pas une liste de couleurs en dur. Une liste en dur nécessite une modification pour chaque nouveau jeton et est oubliée.
• Clear réinitialise les cellules sans les repeindre ; tout ce qui dessine après doit restyler l'arrière-plan. Remplissez les superpositions avec une surface surélevée pour qu'elles flottent au-dessus des panneaux.
• Le Chart de Ratatui peint la zone de tracé via un Canvas dont l'arrière-plan par défaut est Color::Reset. Dans un panneau teinté, définissez l'arrière-plan du graphique sur le remplissage du panneau, pas sur celui de la page : la couleur de la page à l'intérieur d'une carte colorée en surface est le même trou, un niveau au-dessus.

Hit testing couplé au layout

• Si le hit-testing souris reflète le layout dessiné (bandes d'onglets, barres segmentées, champs de statut), modifiez le dessin et les calculs miroir dans la même édition. Préférez les tests basés sur le rendu qui localisent chaque étiquette par la colonne dessinée ; les assertions de rectangles écrites à la main passent alors que le layout réel place le widget ailleurs.
• L'ajout ou l'élargissement d'un symbole de surbrillance de liste décale le texte de chaque ligne. Les zones de ligne cliquables doivent être en pleine largeur ou recalculées pour correspondre.

Glyphes

• La précision des jauges sous-cellulaires utilise les huitièmes de bloc (U+258F..U+2589), Block Elements : chemin Unicode uniquement ; le remplacement ASCII remplit les cellules entières. Graphiques Braille et sparklines aussi : fournissez un substitut ASCII, ne laissez pas les caractères de boîte fuir en mode --ascii.
• Les icônes de colonnes alignées doivent être des symboles BMP monospace. Les emojis sont double-largeur, décalant silencieusement chaque colonne suivante dans la ligne.

Vérification

• Refonte : changez les styles d'abord, le texte ensuite. Les tests de rendu vérifient le contenu textuel, donc les chaînes inchangées maintiennent la suite verte pendant que l'apparence change.
• Porte visuelle : générateur de captures d'écran déterministe du projet (compteur d'images fixe, pas d'horloge, pas d'aléatoire). Le mode de vidage texte est la revue de layout la plus rapide. Validez les images régénérées avec le changement de code source pour que le test de non-dérive du CI réussisse.
• Vérifiez les arrière-plans sur le tampon de cellules, pas sur l'image rendue : le résolveur d'image convertissant Color::Reset en arrière-plan du thème cache exactement les trous que le balayage du tampon détecte.
• Gardez l'animation basée sur un compteur d'images (pulsations, clignotements) déterministe pour des captures d'écran reproductibles.