Theming

Esta página está traducida del inglés. Leer la página en inglés

Estado: implementado en crates/zeyn/assets/zeyn.css.

El UI kit predeterminado lee cada color, fuente, tamaño y radio de propiedades personalizadas de CSS en :root. Una organización cambia la apariencia sobrescribiendo unas pocas. Nunca necesita editar zeyn.css ni escribir selectores.

1. Cómo se aplica un tema

El servidor sirve primero zeyn.css y después, cuando la app tiene una, una hoja de estilos adicional con las sobrescrituras de tokens. El archivo de sobrescrituras solo contiene bloques :root:

:root {
  --z-brand: #7a2448;
  --z-font: "Source Sans 3", "Segoe UI", system-ui, sans-serif;
  --z-radius: 8px;
  --z-density: 0.75;
}

Reglas para el archivo de sobrescrituras:

• Debe servirse desde el propio origen de la app. La Content Security Policy es style-src 'self', por lo que los bloques <style> en línea y las hojas de estilos de terceros se bloquean.
• Las fuentes deben estar ya instaladas en las máquinas de los usuarios o servirse desde el origen de la app. El kit en sí no carga fuentes web.
• Cárgalo después de zeyn.css, para que a igualdad de selectores gane el orden.
• Define los tokens base de la sección 2. Los tokens derivados de la sección 3 los siguen automáticamente. Sobrescribe un token derivado solo cuando el valor calculado no funcione para tu marca.

Temas claro, oscuro y de la app

Toda app tiene un selector de tema en el menú, junto al selector de idioma. Ofrece System (sigue prefers-color-scheme), Light, Dark y cualquier tema que defina la app:

App::new("Billing")
    .theme(Theme::new().brand("#7a2448").radius(6))
    .themes([
        Theme::light(),
        Theme::dark(),
        Theme::named("sand", [("--z-bg", "#f5f1ea"), ("--z-surface", "#fffdf8")]).label(t!("theme.sand")),
    ])
    .default_theme("system")

• App::theme es la apariencia de la organización y se aplica bajo todos los temas.
• App::themes lista lo que los usuarios pueden elegir. Sin ella, la lista es Light y Dark. System se ofrece cuando ambos están en la lista. Theme::named(...) se construye sobre el tema claro; .dark_base() lo construye sobre el oscuro.
• App::default_theme es el tema de los usuarios que no han elegido ninguno. system si no se define.
• App::theme_picker(false) oculta el selector; todos obtienen el tema predeterminado.
• Un solo tema bloquea la app: .themes([Theme::named("acme", tokens)]) o .theme(Theme::dark()).

Los tokens se comprueban cuando arranca la app. App::check (y por tanto router y serve) informa de nombres de token desconocidos, valores que podrían salirse de su declaración (;, llaves, \, <, >, url(), nombres de tema incorrectos, un tema predeterminado desconocido y cada par de colores de la sección 5 que un tema deje por debajo de WCAG 2.2 AA. Solo los valores #rgb y #rrggbb se pueden comprobar en cuanto al contraste; las demás sintaxis de color se dan por buenas.

Todos los temas se sirven en una sola hoja de estilos, /_zeyn/theme.css, construida una vez al arrancar y cargada después de las hojas de estilos del kit. La elección se guarda en la cookie zeyn_theme y, para un usuario con sesión iniciada en una app con un view store (App::datagrid_views), en ese store, de modo que lo sigue a un dispositivo nuevo. El servidor renderiza el tema en <html>, así que el primer pintado ya es correcto y no hace falta ningún script en línea:

Cambiar el tema en el selector solo cambia estos atributos y el meta color-scheme, y luego llama a POST /_zeyn/theme. No se recarga nada.

Para dar al tema oscuro sus propios valores en un archivo de sobrescrituras escrito a mano, repite los selectores que usa el kit:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { --z-bg: #0e1012; }
}
:root[data-theme="dark"] { --z-bg: #0e1012; }

Densidad

--z-density escala la unidad de espaciado. 1 es normal, 0.75 es compacto. <html data-density="compact"> establece 0.75 sin hoja de estilos. Los controles y las filas del grid nunca son más pequeños que 24 px, así que el modo compacto sigue cumpliendo el tamaño de destino de WCAG 2.2.

La altura de fila de un grid virtual la fija el servidor (Paging::virtual_rows(px), 32 px de forma predeterminada) porque el runtime calcula a partir de ella las posiciones de desplazamiento. La densidad no la cambia.

2. Tokens base

Estos son los tokens que se espera que establezca una organización.

3. Tokens derivados

Se calculan a partir de los tokens base con color-mix() y la sintaxis de color relativo. Se actualizan solos cuando cambia un token base.

Tokens por elemento establecidos por el marcado del servidor: --z-width (ancho de ventana), --z-flex (proporción de columna), --z-row-height (altura de fila del grid virtual) y, para la biblioteca de componentes, --z-stack-gap, --z-split, --z-progress, --z-columns, --z-level y --z-pop-x / --z-pop-y (posición de popup).

Los colores de serie de los gráficos son --z-chart-1 a --z-chart-6 en components.css, con valores más claros en el tema oscuro. Cada uno alcanza 3:1 frente a --z-surface. Sobrescríbelos como cualquier token base.

4. Elegir un color de marca

• --z-brand lleva texto blanco en el tema claro (botones, banda del nombre de la app). Elige un color con al menos 4.5:1 frente a --z-on-brand. La mayoría de los colores de marca de tono medio a oscuro lo cumplen. Para un color de marca claro, como el amarillo, establece también --z-on-brand con un color oscuro.
• En el tema oscuro el kit aclara la marca para el texto, los anillos y los botones primarios, y mantiene la marca sólida para la banda del nombre de la app. Una marca distinta se ve intencionada en ambos temas sin un segundo color.
• Mantén los colores de estado distintos de la marca. Una marca roja junto a filas de error rojas dificulta detectar los errores; en ese caso desplaza --z-danger hacia un rojo diferente o mantén la marca fuera de los grids sobrescribiendo --z-brand-subtle.
• Comprueba tus colores usando como objetivo la tabla de la sección 5. Cualquier par por debajo del umbral incumple WCAG 2.2 AA.

5. Contraste verificado

Medido en Chromium sobre la app de ejemplo en ejecución: cada token se resolvió a su valor sRGB renderizado (incluidos color-mix() y los colores relativos), y después se calculó la razón de contraste de WCAG 2.x. Umbrales: 4.5:1 para texto, 3:1 para los contornos de componentes de interfaz y los indicadores de foco.

--z-border es decorativo (divisores entre elementos que ya tienen texto) y no se exige que alcance 3:1.

6. Otros comportamientos de accesibilidad

• Todo elemento interactivo muestra un anillo :focus-visible de 2 px en --z-focus. Las filas del grid dibujan el anillo dentro de la fila para que el contenedor de desplazamiento nunca lo recorte.
• Los botones, las entradas, los encabezados de orden, los cuadros de filtro, los botones del paginador y el botón de cierre de ventana miden al menos 24 x 24 px con cualquier densidad.
• prefers-reduced-motion: reduce elimina la entrada de los toasts y todas las transiciones.
• En el modo forced-colors, los iconos usan CanvasText, el botón primario y la fila con foco usan Highlight, y el estado que depende de tintes de fondo (elemento de menú actual, estado de fila) recibe en su lugar un contorno o borde.