w0rxbend/tui-design-systems

Sistemas de diseño TUI (Ratatui)

Reglas para visuales nuevos o renovados de TUI Ratatui sin romper el modelo de interacción. Para los paneles de terminal Rust de este usuario; combinar con instrucciones locales de la aplicación.

Cuándo Usar

• Nueva capa visual de panel Ratatui (temas, paneles, insignias, medidores, pestañas).
• Rediseñar/restilar una TUI Ratatui existente, especialmente con múltiples temas, selector de temas en vivo, prueba de impacto con ratón o puerta de captura de pantalla determinista en CI.

Arquitectura de tokens

• Mantén las paletas planas, constantes y pocas: una estructura de roles semánticos por tema, intercambiada por puntero. Deriva cada color superpuesto o mezclado como token a partir de esos roles con un único blend() RGB: surface y surface_hi (rellenos de panel, superposiciones), track (extremo de barra vacía), fade (color atenuado hacia el fondo), gradient (trazo de acento), on_color (texto legible de insignia, elegido por luminancia). Una nueva paleta entonces restila cada componente a la vez, como necesita el selector de temas en vivo.
• Los widgets nunca nombran un Color literal, solo tokens del tema.
• Guarda blend() contra puntos finales no RGB: los colores ANSI no tienen canales, así que cae al punto final más cercano, no inventes uno.

Temas sin fondo

• Un tema con fondo Color::Reset (paleta mono/TTY) debe degradar cada relleno: las superficies caen a Reset, las insignias se convierten en texto coloreado entre corchetes, los extremos de barra vacía usan el color del borde, no el track derivado (que es Reset, se renderiza como el color predeterminado de la terminal). Pruébalo: pinta solo Reset y resaltado de selección.

Integridad del fondo

• Barre cada vista × superposición con prueba de buffer de celdas: el fondo de cada celda debe estar en la lista blanca de tokens proporcionada por el tema (is_background), no en una lista de colores fija. La lista fija necesita edición por cada nuevo token y se olvida.
• Clear reinicia las celdas sin volver a pintar; lo que sea que dibuje después debe restilar el fondo. Rellena las superposiciones con una superficie elevada para que floten sobre los paneles.
• El Chart de Ratatui pinta el área del gráfico mediante un Canvas cuyo fondo por defecto es Color::Reset. En un panel con tinte, establece el fondo del gráfico al relleno del panel, no al de la página: el color de página dentro de una tarjeta con color de superficie es el mismo agujero, un nivel arriba.

Prueba de impacto acoplada al layout

• Si la prueba de impacto con ratón refleja el layout dibujado (tiras de pestañas, barras segmentadas, campos de estado), cambia el dibujo y las matemáticas de espejo en la misma edición. Prefiere pruebas basadas en renderizado que localicen cada etiqueta por columna dibujada; las aserciones de rectángulos escritos a mano pasan mientras el layout real coloca el widget en otro lugar.
• Agregar o ensanchar un símbolo de resaltado de lista desplaza el texto de cada fila. Las regiones de filas cliqueables deben ser de ancho completo o recalcularse para coincidir.

Glifos

• La precisión submétrica de medidores usa bloques de octavos (U+258F..U+2589), elementos de bloque: solo ruta Unicode; el fallback ASCII llena celdas enteras. Gráficos Braille y sparklines también: proporciona sustituto ASCII, no filtres dibujo de cajas en modo --ascii.
• Los iconos de columnas alineadas deben ser símbolos BMP de ancho simple. Los emojis tienen ancho doble, desplazando silenciosamente cada columna posterior en la fila.

Verificación

• Rediseño: cambia estilos primero, texto después. Las pruebas de renderizado afirman el contenido del texto, así que las cadenas intactas mantienen la suite verde mientras el aspecto cambia.
• Puerta visual: el generador de capturas de pantalla determinista del proyecto (contador de fotogramas fijo, sin reloj, sin RNG). El modo de volcado de texto es la revisión de layout más rápida. Confirma las imágenes regeneradas con el cambio de fuente para que la prueba de no-deriva del CI pase.
• Verifica los fondos en el buffer de celdas, no en la imagen renderizada: el escritor de imágenes que resuelve Color::Reset al fondo del tema oculta exactamente los agujeros que captura la barrida del buffer.
• Mantén la animación impulsada por contador de fotogramas (pulsos, parpadeos) determinista para capturas de pantalla reproducibles.