Saltar al contenido

Theming

Se definen unas pocas semillas de color, en hex o en oklch, y el motor genera las escalas completas, el modo oscuro y el texto de cada color. Cada paso se calcula por contraste, no a ojo.

Cómo funciona

Cada familia de color parte de una semilla: un hex (#3b82f6) o un color en OKLCH (oklch(0.62 0.19 259)). El motor arma 10 pasos (100→1000) y a cada uno le fija un contraste concreto contra el fondo: el 100 apenas se distingue de él, el 1000 es casi negro en claro y casi blanco en oscuro. Por eso el paso 500 se comporta parecido con cualquier color, sea un azul, un lima o un rojo.

El tono se mantiene a lo largo de la escala, y la saturación nunca supera la de tu semilla: una semilla apagada da una escala apagada. La excepción son los amarillos, que al oscurecerse tiran al naranja en vez de ponerse verdosos. El modo oscuro no es un espejo del claro: se calcula de nuevo contra el fondo oscuro con el mismo criterio, así que --color-brand-500 "hace lo correcto" en claro y en oscuro. Ver la página de Tokens para todas las escalas resultantes.

Esto es lo que calcula el motor para #3b82f6. «Fondo» es el contraste WCAG del paso con el fondo de la página; «texto» es el contraste del texto que va encima (el -contrast de ese paso), en WCAG y en APCA (Lc).

Paso Claro · fondo Claro · texto Oscuro · fondo Oscuro · texto
1001,1:118,2 · Lc 1001,0:118,4 · Lc 103
2001,2:116,1 · Lc 921,1:117,1 · Lc 102
3001,5:113,1 · Lc 801,3:114,7 · Lc 101
4002,1:19,4 · Lc 631,8:110,6 · Lc 95
5003,7:1 · tu color5,3 · Lc 403,4:15,6 · Lc 80
6006,0:15,3 · Lc 765,5:1 · tu color5,1 · Lc 39
7008,5:17,6 · Lc 847,8:17,2 · Lc 53
80012,0:110,7 · Lc 9211,0:110,2 · Lc 69
90016,0:114,2 · Lc 9615,0:113,9 · Lc 86
100019,0:116,9 · Lc 9818,0:116,7 · Lc 97

Tu color queda exacto

La semilla no es una sugerencia: aparece tal cual en el paso que le corresponde por su luminosidad. Con #3b82f6, tu azul queda en el paso 500 en claro y en el 600 en oscuro; el resto de la escala se calcula alrededor.

Hay una franja de luminosidad media donde ningún texto, ni claro ni oscuro, llega a contraste AA sobre el color. Si tu semilla cae justo ahí, se corre al borde más cercano (como mucho 3 puntos de luminosidad) y el Theme editor te lo avisa con cuánto y por qué. Gana la legibilidad.

Esa escala es la paleta de tu marca. El relleno de los botones y los controles no sale del paso que ocupa la semilla sin más, sino del «sólido» (siguiente sección): ahí una marca negra o muy oscura queda como se escribió.


El texto sobre cada color

Cada paso trae su texto: --color-brand-600-contrast es el gris del sistema (el más claro o el más oscuro del modo) que mejor se lee sobre --color-brand-600. En todos los pasos y con cualquier semilla, ese texto llega a contraste AA para texto normal (4,5 o más): es una propiedad del cálculo, no algo que se revise a mano.

Además del contraste WCAG 2, que es el criterio obligatorio, se mide APCA (Lc; más alto, más legible). APCA no decide nada: se muestra en el Theme editor para ver dónde los dos métodos discrepan, sobre todo en los tonos medios.


El relleno de tu marca

El botón primario, el checkbox, el radio y el toggle encendidos se pintan con el primario del tema; si no se define, con tu marca (brand). Con brand: '#7c3aed', el botón es violeta; para tener botones negros con esa marca violeta, se agrega primary: 'oklch(0.15 0 0)' al tema (al lado de colors, como focusRing). Así lo hace el tema de esta documentación: marca azul, botones negros. Lo demás de marca (badges, avatares, barras de progreso, variant="brand") sigue a brand.

Para que se vea bien en claro y en oscuro, el motor elige solo el paso de la escala que hace de relleno, el sólido:

  • En claro: si tu marca es más oscura que el tono operativo de la familia (el paso 600), se usa tu color exacto. Si es más clara, se usa ese tono 600, que es el que sostiene texto blanco encima.
  • En oscuro: una marca neutra (negro o gris) se invierte, igual que el resto de los grises: el negro pasa a blanco. Una marca de color usa un tono más claro, legible sobre el fondo oscuro.

Los estados (success, danger, info, warning) siguen la misma regla, y las variantes de color de esos cuatro componentes (variant-danger, etc.) usan el sólido de su familia.

El primario expone el suyo con el mismo nombre (--color-primary-solid y el resto; no tiene escala, así que bg-primary-500 no existe). Cada familia expone el sólido como variables, para usarlo en tus propios componentes: --color-brand-solid, --color-brand-solid-hover y --color-brand-solid-active, cada una con su texto (--color-brand-solid-contrast, -solid-hover-contrast, -solid-active-contrast), que siempre llega a contraste AA. Valen para brand, para cualquier color que se agregue y para los estados.

css

También hay utilidades: bg-brand-solid, bg-brand-solid-hover, bg-brand-solid-active, el texto color-brand-solid-contrast (y las de hover y active) y outline-brand-solid.

html

Una marca blanca no puede ser el relleno

Si la semilla es casi blanca, no se ve sobre el fondo claro y el sólido no puede ser blanco: sale gris (el paso 600). taisho generate lo avisa, igual que el Theme editor y, en desarrollo, createTheme (un console.warn por semilla; sin bundler, como por CDN, avisa siempre). Para un botón blanco conviene una variante con borde; para la marca, una semilla más oscura.

Pantallas P3

Una pantalla P3 muestra colores más saturados que una sRGB. El motor calcula las dos escalas con los mismos nombres de variable y el navegador usa la de la pantalla (media query color-gamut: p3). Ningún color queda fuera de lo que la pantalla puede mostrar, así que el navegador no tiene que recortarlo ni deformarlo; en sRGB se ve la escala sRGB y en P3 se ganan pasos más vivos. Una semilla en oklch que sólo existe en P3 se ve exacta en esas pantallas y se acerca todo lo posible en sRGB.


Grises

Los grises (--color-gray-*) son neutros puros por defecto. Para que tengan un aire de tu marca, el tema acepta un tinte: c es cuánto color (0.01 apenas se nota) y h el tono en grados. El tinte conserva la luminosidad de cada gris y se desvanece hacia el blanco y el negro, que quedan neutros. El texto de cada paso se mide contra los grises que el tema realmente usa.

ts

En el Theme editor, la opción «De marca» hace justamente eso con el tono de tu semilla de marca.


Daltonismo

El color nunca debería ser la única señal: un estado también se dice con texto, un ícono o una forma. Para comprobar qué pasa con tu paleta, el Theme editor trae una vista de daltonismo que simula deuteranopía, protanopía y tritanopía sobre las escalas y la vista previa.


Tres maneras de usarlo

Hay tres maneras de aplicar un tema, de la más corta a la más a medida. Conviene la que alcance: no hace falta pasar por las anteriores.


1. Usar el tema ya hecho

Es el camino sin instalar nada. El primer <link> de la guía de instalación trae los valores del tema; el segundo, las reglas que los usan. El tema va primero, siempre.

html

El tema compilado es taisho: marca negra (oklch(0.15 0 0), el mismo gris 1000, que en oscuro se ve blanca), secundario lima y acento ámbar. Es el que usa esta documentación. Para otros colores, siguen los dos caminos de abajo.


2. Repintar en el navegador

Con createTheme se pasan las semillas propias y el tema se aplica al instante, sin compilar nada. Se monta encima del tema cargado por <link>: sólo pisa lo que se define, y llamarlo de nuevo reemplaza el anterior en vez de acumular. Sirve, por ejemplo, para que cada cliente de tu app tenga su color.

ts

createTheme acepta las mismas claves de tema que el config, salvo components: colores, escalas (fontSizes, shadows, motion…), density, focusRing y locked. Cambia valores de niveles que ya existen; sumar niveles nuevos (extend) se compila.

createTheme es el export principal de @taishods/core. Se instala con npm i -D @taishods/core, como en el camino 3, y el <script> del CDN no lo incluye. Para no depender de un paquete, el camino 3 da el mismo resultado compilado.

3. Compilar tu propio CSS

Tus semillas viven en un taisho.config.ts en tu proyecto y el CLI las compila a un CSS con tus paletas ya calculadas. Cada cambio de marca es editar el config y volver a correr el comando (build-time, no runtime).

bash

generate escribe theme.css con tus tokens, fonts.css y el sistema: taisho.css con sólo lo que usan tus archivos si se declara content en la config, o taisho.full.css completo si no. Al terminar te imprime los <link> exactos para pegar. Tu tema reemplaza al primer <link> del camino 1.

De dónde sale el comando

El CLI viaja en @taishods/core: con npm i -D @taishods/core se obtiene el comando taisho. Pide Node 22.18 o más nuevo. Para usar íconos, se instala también npm i -D lucide-static, de donde salen los nombres.

Qué lleva el config

Un tema es una entrada de themes: su clave es el nombre del archivo de salida y adentro van las semillas de marca y, si hace falta, algunos overrides.

ts

Los estados (success, warning, info, danger) salen de defaultStates; un tema puede sobrescribirlos con su propio campo states. El fondo y el borde de cada estado (--ts-color-*-bg, -border) salen de las shades 100 y 200 de su paleta, así que cambian solos al mover las semillas.

brand es obligatorio en cada tema: de esa semilla salen el relleno de los botones primarios, de los checkbox, radios y toggles encendidos, los enlaces y los acentos. Sin él, taisho generate corta con un error que dice qué tema falta y qué poner, y el editor marca el tipo antes de correr nada. Los demás colores (brand-secondary, accent…) son opcionales y con el nombre que se quiera.

Si tu marca queda casi del mismo color que un estado (una marca roja con el danger de fábrica, por ejemplo), un botón primario y uno de peligro se verían iguales. En ese caso taisho generate avisa, sin cortar, con la distancia medida, y la salida es definir ese estado aparte en defaultStates. El aviso salta por debajo de 0,05 de distancia entre colores (ΔE en OKLab), una diferencia que a simple vista casi no se nota.

Además de los colores, cada tema puede pisar sus fonts, radius, spacing, shadows, los grises (neutral) y las superficies (material), y también la tipografía, los trazos, el movimiento y la densidad (más abajo). Para sumar nombres nuevos —un screen, un radio, un tamaño de texto, una clase propia— están extend y utilities: en el config se declaran nombres y en el tema se cambian valores. Cada escala está en la página de Tokens con sus valores. Las clases que genera siguen la gramática de Nombres de clases.

focusRing define el color del aro de foco de todo el sistema (--ts-focus-ring-color) con cualquier valor CSS, por ejemplo 'var(--color-brand-600)'. Si no se define, sale de tu marca.


Color del foco

El foco (lo que ves al navegar con el teclado) es una línea fina pegada al borde y un halo del mismo color, más transparente. El color sale de la opción focusRing del tema, que acepta cualquier color CSS válido, también una variable del sistema; si no se define, de tu marca. Los botones y campos de un color (danger, success…) usan el suyo. Para tus propios componentes: focus-ring dibuja el foco y focus-ring-danger (o cualquier color de tu tema) elige el color.

ts

Forma de las esquinas

La opción cornerShape del tema elige entre esquinas redondas ('round', la de siempre) y 'squircle', una curva más suave que se funde con el lado en vez de cortarlo en arco. Vale igual en createTheme, en themes del config y en la config interna. Sale como la variable --ts-corner-shape, que leen todas las clases radius-* y los componentes con radio. Un valor que no sea ninguno de los dos corta taisho generate con la ruta exacta. En un tema bloqueado (locked) se ignora, como los demás overrides.

El squircle lo dibuja corner-shape, hoy sólo en Chromium. Con la misma medida, esa curva se ve más cerrada que un arco, así que con 'squircle' cada radio sube un paso: xs toma el valor de sm, sm el de md, y así hasta 2xl, que toma el de 3xl. 3xl queda igual, y none y full no se mueven. Los radios que el tema cambia suben con su valor nuevo. Los nombres que suma extend.radius toman la forma pero no suben. El motor lo calcula; no hay que tocar nada más.

Todo va dentro de @supports (corner-shape: squircle): en Firefox y Safari el token queda en round y los radios no suben, así que todo se ve redondo con las medidas de siempre. Con cornerShape: 'round' explícito en createTheme, se puede pisar una base compilada con squircle.

ts

Tipografía

Son dos cosas distintas: la pila CSS que usan los tokens (--font-sans) y qué archivos se descargan. En el config son fonts y fontFaces; el fonts.css que sale de generate se arma desde la segunda.

ts

Los paquetes @fontsource/* tienen que estar en el package.json de tu proyecto. Cada combinación de alfabeto y peso es un archivo más que baja el usuario: latin alcanza para castellano, y declarar de menos es gratis mientras que declarar de más se paga en cada visita.

Para <em>, citas y énfasis con la itálica real de la fuente (si no, el navegador inclina la normal), se suma styles: ['normal', 'italic']. Sin styles se baja sólo la normal. Cada peso y alfabeto suma un archivo itálico, y la fuente tiene que traerlo: si el paquete no tiene itálica para ese peso, generate corta con un error que lo nombra.

ts

Cambiar y sumar niveles de cada escala

Cada escala del sistema (tamaños de texto, sombras, duraciones, medidas…) se toca desde dos lugares con la misma ruta. En el tema, themes.<tema>.<escala> cambia el valor de un nombre que ya existe. En extend.<escala> se suman nombres nuevos, que valen para todos los temas y generan su variable y sus clases. extend sólo agrega: pisar un nombre del sistema es un error, y un nombre que la escala no tiene, escrito dentro de un tema, también (el mensaje dice dónde sumarlo).

Escala En el tema: cambia el valor En extend: suma niveles Genera
Tamaños de textofontSizesfontSizes--ts-fontsize-N · text-N · type-heading-N · type-copy-N
InterlineadoslineHeightslineHeights--ts-lh-N · leading-N
Espaciado entre letrasletterSpacingletterSpacing--ts-ls-* · tracking-*
Pesos de fuentefontWeightsfontWeights--ts-fw-* · weight-*
Anchos de trazoborderWidthsborderWidths--ts-border-width-N · border-N · ring-N
Desenfoquesblursblurs--ts-blur-* · blur-* · backdrop-blur-*
Opacidadesopacitiesopacities--ts-opacity-N · opacity-N
Sombrasshadowsshadows--ts-shadow-* · shadow-* · surface-* · floating-*
Duraciones y curvasmotion.durations · motion.easingsmotion.durations · motion.easings--ts-duration-* · duration-* · --ts-ease-* · ease-*
Radiosradiusradius--ts-radius-* · radius-* · --ts-corner-shape (opción cornerShape)
Gaps y spacesspacing.gaps · spacing.spacesspacing.gaps · spacing.spaces--ts-gap-* · --ts-space-* · gap-* · p-* · m-*
Screensscreensscreens--ts-screen-* · variantes de screen
Medidasfija: no se cambiasizing: [30, 100]--ts-sizing-N · p-N · w-N · h-N · size-N · gap-N · icon-N…
Capas (z-index) y loopszIndex · motion.loopsno se amplían--ts-z-* · --ts-duration-spin…
ts

Los niveles que se suman se usan como cualquier otro:

html
  • Nombres. En los tamaños de texto, interlineados y anchos de trazo el nombre es un número entero de 1 a 999; en las opacidades, de 0 a 100; en sizing, la lista de px. El resto va en minúsculas y guiones.
  • Valores. Una opacidad va de 0 a 1 (o es un var()), un peso de 1 a 1000, una duración en ms o s, un z-index es un entero. Un valor que podría cerrar la declaración CSS (; o llaves) se rechaza.
  • Un tamaño de texto lleva su interlineado. Cada extend.fontSizes necesita un lineHeights con el mismo nombre. Los de 14 en adelante suman type-heading-N y los de 12 a 24, type-copy-N. Si se cambia fontSizes en un tema sin tocar lineHeights, el interlineado queda como estaba.
  • Medidas. sizing es fija: se suman niveles, pero ningún tema cambia el valor de uno existente. Cada nivel nuevo trae sus clases y el modificador icon-N del ícono, que el componente Icon usa con un size numérico.
  • Movimiento. Una duración que se suma también baja a 1 ms con «reducir movimiento» del sistema. Las animaciones infinitas (loops) no se amplían, y con «reducir movimiento» el skeleton y la barra indeterminada quedan quietos (motion.iterations).
  • Sombras. Una sombra nueva genera shadow-*, surface-* y floating-*; no llega a las superficies material-*, que llevan las suyas.
  • El foco. Los anchos de trazo 1 y 4 dibujan la línea y el halo del foco: con valor 0 desaparecen. taisho generate avisa, sin cortar.
  • Idiomas que se escriben de derecha a izquierda. En árabe, persa, urdu y hebreo el interlineado y el espaciado entre letras siguen los de tu tema, con un interlineado de al menos 1,35. Si lo das con var(), la variable tiene que valer una longitud, no un número suelto.
  • Un tema locked ignora los valores que defina, pero recibe todo lo que se sumen en extend.
  • Autocompletado. Si se suman niveles en extend o se declaran utilities, taisho generate escribe taisho.classes.d.ts con tus clases propias: debe quedar dentro del include de tu tsconfig y entran en TaishoClass.

Densidad del tema

La densidad es el tamaño de los controles (alto, relleno, casillas) en modo normal y en modo compacto (class="ts compact"). Cada tema puede cambiar los px de cada familia y talle con density: las familias son control-h, button-px, field-px, select-pr, textarea-px, textarea-py, badge-h, badge-px, tag-h, tag-px, control-box y radio-dot, y los talles sm, md y lg (xs sólo en control-h y button-px). En compact.spacing se cambian los gaps y spaces que el modo compacto achica (none, quarter, half, base, section, double); los que se suman en extend no se compactan.

ts

Lo que no se define queda con el valor de fábrica. Cuando un tema define densidad, la clase density-compact (o density-comfortable) de un componente suelto, como class="ts button density-compact", también toma sus valores; createTheme aplica la densidad del tema a la página, pero no llega a esa clase.


Modo oscuro y densidad (runtime)

Ambos se controlan con una clase en <html>, así que se togglean en el navegador sin recompilar nada y funcionan igual con cualquiera de los tres caminos:

ts

Seguir el modo del sistema

Con darkMode: 'media' en la config, la página sigue la preferencia del sistema del visitante desde el primer pintado, sin ningún script en el <head>. La clase dark en <html> la fuerza a oscuro y la clase light la fuerza a claro: es lo que usa un selector de tema dentro de tu app. El valor predeterminado es 'class': el modo oscuro se activa sólo con la clase.

ts
La opción se aplica al generar el CSS. El archivo listo para usar desde el CDN activa el modo oscuro con la clase dark.

Secciones con modo fijo

Un pie o un panel lateral oscuros en un SaaS claro no cambian cuando cambia la página. scheme-dark y scheme-light fijan el modo de un elemento y de todo lo que tiene adentro: los colores, los componentes y el color del texto se resuelven en ese modo, sin importar el de la página. Pintale también el fondo, porque la clase fija el modo y no pinta el elemento:

html

Los colores fijos salen de la misma escala: scheme-dark bg-background-100 es un fondo casi negro en los dos modos y scheme-light bg-background-100, uno blanco. Una NavBar dentro de la sección toma el fondo de esa sección sin ninguna variante.

Los menús, diálogos y avisos que se abren sobre la página toman el modo de la página, no el de la sección desde la que se abrieron.