Ir al contenido

Temas

Un tema es un objeto JSON. Pasa un nombre o un objeto; los objetos se combinan en profundidad sobre un tema base, así que solo escribes lo que cambia.

plot({ ...spec, theme: 'noche' });                         // built-in dark theme
plot({ ...spec, theme: { extends: 'noche', marks: { lineWidth: 3 } } });
plot({ ...spec, palette: 'okabe-ito' });                    // shortcut for theme.categorical
plot({ ...spec, palette: 'nordico' });                      // una familia: rampas a juego, claro y oscuro
plot({ ...spec, palettes: ['cdia', 'arcilla', 'tinta'] });  // alternativas en un SVG
plot({ ...spec, ramp: 'teal' });                            // shortcut for theme.sequential

Valores por defecto de toda la biblioteca

configure({ font: 'Poppins', textScale: 1.4, theme: { extends: 'papel', marks: { lineWidth: 2.5 } } });

Cada plot(), render(), toHTML() y dashboard posterior parte de estos valores; la especificación siempre manda. El objeto theme propio de una especificación se combina en profundidad sobre el tema global, así que configure({ theme: 'noche' }) más theme: { marks: { barRadius: 0 } } sigue siendo oscuro. configure() devuelve los valores por defecto actuales y configure(null) los borra.

Tu propio tema, en todas partes

El tema por defecto (papel) nunca cambia a menos que lo pidas. Para cambiar el estilo de todos los gráficos, registra un tema una vez y déjalo como predeterminado:

import { registerTheme, configure } from 'plotagents';

registerTheme('acme', {
  extends: 'papel',              // or 'noche', or another registered theme
  background: '#FFFFFF',         // alias of surface
  text: '#111827',               // alias of ink
  lede: '#4B5563',
  muted: '#6B7280',
  grid: { color: '#EEF0F4', dash: '2 3', width: 1 },
  axis: '#C7CBD6',
  categorical: 'tab10',          // any palette or matplotlib qualitative map
  sequential: 'viridis',         // any colormap name
  tooltip: { bg: '#111827', ink: '#FFFFFF' },
  radius: 2,                     // bar, tile and swatch corners
  font: 'Inter',                 // Google Fonts name or CSS stack
});

configure({ theme: 'acme' });

theme: 'acme' también funciona en cada gráfico, y { extends: 'acme', … } se construye sobre él. Los colores se validan: todo lo que no sea un color CSS (hex, rgb(), hsl() o un nombre de color) se descarta y se mantiene el valor base.

Temas incluidos

NombreModoSuperficieUso
papel (alias light)claro#FCFBF9 papelpor defecto
noche (alias dark)oscuro#0B0F2B azul marino profundopáginas oscuras, presentaciones

Ambos comparten los mismos ocho tonos, escalonados por separado para cada superficie y validados sobre ella.

Claves

ClaveTipoSignificado
extendsnombre u objeto de temaBase sobre la que se combina (por defecto papel, o noche cuando mode: 'dark').
mode'light' | 'dark'Afecta los tooltips y el contraste del texto sobre rellenos.
surface (alias background)colorFondo del gráfico. También se usa en las separaciones de 2 px y en los anillos alrededor de las marcas.
ink (alias text), lede, mutedcolorTexto principal, texto secundario, texto de ejes y de la fuente.
gridcolor o { color, dash, width }Líneas de cuadrícula (por defecto 1 px, continuas). dash: '2 3' dibuja líneas de cuadrícula punteadas.
axiscolor o { color, width }Líneas base.
tooltip{ bg, ink }Colores de la tarjeta del tooltip en el navegador (por defecto: tarjeta blanca en temas claros, azul marino en oscuros).
radius, barRadiusnúmeroRadio de las esquinas de las barras (por defecto 4). radius lo fija para todas las marcas que tienen esquinas.
tint, tint2colorRellenos discretos: tarjetas KPI, rieles de deslizadores, medidores.
dimcolorMarcas atenuadas cuando se usa highlight.
othercolorEl grupo "Otros" y las series desde la novena.
categoricalcolores, paleta o nombre de mapa de coloresColores de identidad, asignados en este orden.
sequentialcolores, rampa o nombre de mapa de coloresDe claro → oscuro, para mapas de calor y mapas.
divergingcolores, rampa o nombre de mapa de coloresDos polos con un punto medio neutro.
status{ good, warning, critical }Deltas y medidores de KPI. Nunca se usa para series.
font{ family, mono, import }Pila de fuentes y URL opcional de su hoja de estilos (fontImport: true la incrusta en el SVG). Desde un spec, import debe ser https en Google Fonts, Bunny Fonts, Adobe Fonts (Typekit) o cdnfonts; otros hosts se descartan. Los temas registrados con registerTheme() conservan cualquier URL https, y configure({ fontHosts: ['fonts.ejemplo.com'] }) permite más hosts.
type{ title, subtitle, label, axis, legend, source, titleWeight }Tamaños de letra en px. Los títulos se achican de forma automática en anchos angostos.
marks{ barRadius, barMax, barMaxH, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity }Geometría de las marcas.
axes{ inside, grid }inside: true pone las etiquetas de y sobre sus líneas de cuadrícula, dentro del gráfico (más ancho para los datos).
layout{ padding }Margen exterior de todos los gráficos con este tema (mismas formas que la opción padding). Por defecto 8 arriba y abajo, 0 a los lados.

Familias de paletas minimalistas

Además de la paleta de fábrica (cdia) hay tres familias minimalistas: cinco colores apagados cada una, una versión para fondo claro y otra para fondo oscuro, y una rampa secuencial y una divergente a juego. Desde la 6ª serie, las marcas van en gris ("Otros") y lint sugiere highlight o facet.

plot({ ...spec, palette: 'nordico' });                    // categórica + rampas a juego
plot({ ...spec, palette: 'nordico', theme: 'noche' });    // la misma familia, escalonada para fondo oscuro
configure({ palette: 'arcilla' });                        // todos los gráficos
NombreFamiliaClaro (orden fijo)
cdiaCDIA#3A47B8 #D42A5E #E8A33D #1E9C89 #7B5CD6 #B5562E #5BA3E0 #8E9A2F
arcillaArcilla#A45A40 #979873 #6E4C4C #699DB6 #CEAD87
nordicoNórdico#345785 #B98A8D #386E57 #97B7D9 #D1AB69
tintaTinta#3B538A #919EBB #834A41 #E1A675 #6179AD

Son apagadas a propósito, así que se validan con un piso de croma de 0,04 en vez de 0,10 (validatePalette(colores, { minChroma: 0.04 })); lo demás es la misma prueba que la paleta de fábrica, en su orden fijo: banda de luminosidad, separación para daltonismo entre vecinos (ΔE ≥ 11,7, meta 8) y entre todos los pares (≥ 7,2), y visión normal (ΔE ≥ 15). Con poco croma, los colores se distinguen sobre todo por luminosidad.

Las rampas de la familia sólo reemplazan a las de fábrica: ramp, colorScale o un tema con su propia sequential / diverging siguen mandando. Cada nombre sirve también suelto: theme: { categorical: 'nordico' }, 'nordico-noche' para la lista oscura, ramp: 'nordico' y 'nordico-diverging'. paletteFamilies las exporta todas y familyColors(nombre, modo) devuelve { categorical, sequential, diverging } para un modo.

Varias alternativas en un SVG

palettes escribe las alternativas en el mismo archivo, para que el lector (o tu página) cambie el aspecto sin un SVG nuevo:

plot({ ...spec, palettes: ['cdia', 'arcilla', 'nordico', 'tinta'] });   // o palettes: true para todas las familias
<html data-palette="nordico">   <!-- sirve cualquier ancestro; sin el atributo se ve la primera -->

El primer nombre (o palette, si viene) es la de por defecto y va en los atributos, así que un <img> la muestra. Cada una de las otras es una piel bajo [data-palette="nombre"]; los mapas de calor, mapas y treemaps cambian también sus rampas. toHTML() agrega una fila de botones que pone data-palette en la página, los dashboards pasan palettes a cada gráfico y configure({ palettes }) lo activa en todos (palettes: null lo apaga en uno).

Paletas y rampas con nombre

Paletas (categorical)Rampas (sequential / diverging)
cdia (por defecto), cdia-noche, las familias de arriba (arcilla, nordico, tinta, y cada -noche), okabe-ito, tableau10, udec, más las de matplotlib tab10, tab20, tab20b, tab20c, Set1, Set2, Set3, Pastel1, Pastel2, Paired, Accent, Dark2indigo, magenta, teal, amber, indigo-magenta, teal-rust, cada familia y <familia>-diverging, más todos los mapas de colores de matplotlib (consulta Escalas de color)

Validar una paleta

import { validatePalette } from 'plotagents';

validatePalette(['#223C6A', '#E69B0A', '#D21428'], { mode: 'light', surface: '#FFFFFF', locale: 'en' });
// { ok: false, checks: [
//   { name: 'lightness', status: 'fail', detail: 'Outside the lightness band 0.43–0.77: #223C6A' }, … ] }
PruebaUmbralPor qué
Banda de luminosidadOKLCH L 0.43–0.77 (claro), 0.48–0.67 (oscuro)Demasiado claro desaparece; demasiado oscuro se lee como texto.
Croma mínimoOKLCH C ≥ 0.10Por debajo, un tono se lee como gris.
Separación para daltonismoΔE OKLab × 100 ≥ 8 entre vecinos, con protanopía y deuteranopía simuladas (Machado 2009)Los vecinos deben seguir distinguiéndose con deficiencias de visión del color.
Separación con visión normalΔE ≥ 15Los vecinos deben ser fáciles de distinguir para todos.
Contraste con la superficie≥ 3:1, solo advertenciaPor debajo, las marcas necesitan etiquetas visibles.

Usa pairs: 'all' para diagramas de dispersión y mapas, donde dos colores cualesquiera pueden quedar uno al lado del otro. La paleta incluida pasa la prueba de todos los pares para sus tres primeros colores; por eso lint advierte sobre diagramas de dispersión con más de tres grupos.

lint(spec) ejecuta esta validación de forma automática cada vez que una especificación trae su propia paleta. Los mensajes siguen locale (español por defecto, 'en' para inglés).

Colores que decide la página

Cualquier color de un spec (colors, palette, ramp, colorScale, cualquier clave del tema) puede ser una variable CSS con un respaldo:

plot({ ...spec, palette: ['var(--accent, #3A47B8)'], theme: { ink: 'var(--ink, #141A3F)', grid: 'var(--rule, #E9EBF3)' } });

La marca se escribe con la variable, así que una sección, un modo oscuro o un cambio de marca en la página la recolorea sin un SVG nuevo. Con el respaldo calcula la biblioteca (el texto sobre una marca elige blanco u oscuro a partir de él, los tintes se mezclan desde él), y es lo que muestra el SVG fuera de la página, en un <img> o en un archivo. Una variable sin respaldo hex o rgb() es un error.

Pieles: varios juegos de colores en un SVG

Un sitio estático no puede entregar otro relleno cuando el lector cambia de aspecto: el relleno ya está en el archivo. skins escribe todos los juegos en el mismo SVG y deja que el CSS de la página elija:

plot({
  ...spec,
  skins: [
    { palette: ['#6E86C8', '#D9714F'] },                                     // la de siempre, en los atributos
    { when: 'html.classic', palette: ['#0B3F8C', '#D52B1E'], theme: { surface: '#FFFFFF' } },
  ],
});

Cada piel cambia sólo colores (theme, palette, ramp, colorScale, colors) y se dibuja aparte; donde dos pieles difieren, la marca recibe una variable CSS definida en el <style> del propio SVG bajo el selector when de cada piel. Los atributos conservan la primera piel, así que un <img> y el resaltado desde la leyenda siguen funcionando. Posiciones, textos y orden tienen que salir iguales en todas las pieles; si no, plot lanza un error. Las pieles se combinan con los colores como variables CSS, y configure({ skins }) las fija para todos los gráficos (skins: null las apaga en uno).

El color sigue a la entidad

Los colores se asignan a entidades, nunca a posiciones:

  • Con time, los colores se calculan sobre todos los períodos, así que un grupo mantiene su color mientras se mueve el deslizador aunque cambie su posición en el ranking.
  • Con focus (navegación en profundidad), el subárbol mantiene la familia de colores de su padre.
  • Con facet, todos los paneles comparten un mismo mapa de colores.
  • colors: { "Copper": "#B5562E" } fija cualquier entidad a un color.

Editar esta página en GitHub