w0rxbend/tui-design-systems

Sistemas de design para TUI (Ratatui)

Regras para visuais TUI novos ou reformulados com Ratatui sem quebrar o modelo de interação. Para os painéis de terminal Rust deste usuário; combinar com instruções do app local no repositório.

Quando usar

• Nova camada visual de dashboard Ratatui (temas, painéis, badges, medidores, abas).
• Redesenhar ou reestilizar um TUI Ratatui existente, especialmente com múltiplos temas, seletor de tema ao vivo, hit-testing com mouse ou portão de screenshot determinístico no CI.

Arquitetura de tokens

• Manter paletas planas, constantes, poucas: uma struct de função semântica por tema, trocada por ponteiro. Derivar toda cor em camadas ou mesclada como token dessas funções com uma única blend() RGB: surface e surface_hi (painel, preenchimentos de sobreposição), track (extremidade de barra vazia), fade (cor escurecida em direção ao fundo), gradient (sequência de acento), on_color (texto legível em badge, escolhido por luminância). Uma nova paleta então reestiliza todos os componentes de uma vez, conforme necessário pelo seletor de tema ao vivo.
• Widgets nunca nomeiam Color literal, apenas tokens do tema.
• Proteger blend() contra extremidades não-RGB: cores ANSI não têm canais, então aproximar da extremidade mais próxima, não inventar uma.

Temas sem fundo

• Tema com fundo Color::Reset (paleta mono/TTY) deve degradar todo preenchimento: superfícies caem para Reset, badges tornam-se texto colorido entre colchetes, extremidades de barra vazia usam cor da borda, não o track derivado (que é Reset, renderiza como cor de texto padrão do terminal). Testar que pinta apenas Reset e destaque de seleção.

Integridade de fundo

• Percorrer toda visualização × sobreposição com teste de buffer de células: cada fundo de célula deve estar na lista branca fornecida pelo tema (lista de tokens is_background), não em lista de cores fixas. Lista fixa precisa de edição por novo token e é esquecida.
• Clear redefine células sem repintar; o que quer que desenhe depois deve reestilizar o fundo. Preencher sobreposições com superfície elevada para que flutuem acima dos painéis.
• O Chart do ratatui pinta a área do gráfico via Canvas cujo fundo padrão é Color::Reset. Em painel colorido, definir fundo do gráfico como o preenchimento do painel, não da página: cor da página dentro de cartão com cor de superfície é o mesmo buraco, um nível acima.

Hit testing acoplado ao layout

• Se o hit-testing com mouse espelha o layout desenhado (tiras de abas, barras segmentadas, campos de status), alterar desenho e matemática do espelho na mesma edição. Preferir testes orientados por renderização localizando cada rótulo pela coluna desenhada; asserções de retângulo escritas à mão passam enquanto o layout real coloca o widget em outro lugar.
• Adicionar ou alargar símbolo de destaque de lista desloca o texto de cada linha. Regiões clicáveis de linha devem ter largura total ou ser recalculadas para coincidir.

Glifos

• Precisão sub-célula do medidor usa blocos de oitavos (U+258F..U+2589), Elementos de Bloco: apenas caminho Unicode; fallback ASCII preenche células inteiras. Gráficos Braille e sparklines também: fornecer substituto ASCII, não vazar desenho de caixa no modo --ascii.
• Ícones de colunas alinhadas devem ser símbolos BMP de largura única. Emojis têm largura dupla, deslocando silenciosamente cada coluna posterior na linha.

Verificação

• Redesign: alterar estilos primeiro, texto depois. Testes de renderização verificam conteúdo textual, então strings intocadas mantêm suíte verde enquanto a aparência muda.
• Portão visual: gerador de screenshot determinístico do projeto (contador de quadros fixo, sem relógio, sem RNG). Modo de saída de texto é a revisão de layout mais rápida. Commitar imagens regeneradas com alteração de fonte para que a verificação de não-derivação do CI passe.
• Verificar fundos no buffer de células, não na imagem renderizada: o resolvedor de imagem de Color::Reset para fundo do tema esconde exatamente os buracos que a varredura de buffer pega.
• Manter animação orientada por contador de quadros (pulsos, piscadas) determinística para screenshots reproduzíveis.