Saltar al contenido

Variantes

Una variante es un prefijo que hace que una clase valga sólo en cierta situación: con el puntero encima, con el campo deshabilitado, al imprimir o en una pantalla ancha. Se escribe delante de la clase, con dos puntos.

Cómo se escriben

bg-gray-100 pinta el fondo siempre. hover:bg-gray-200 lo pinta sólo mientras el puntero está encima. La variante no cambia el nombre de la clase: se lee igual y se suma a la llave ts como cualquier otra. Se ve al pasar el puntero por la tarjeta o al navegar con el teclado hasta ella.

Puntero y foco

Una tarjeta que cambia de fondo con el puntero y cuando el foco llega por teclado.

html

El vocabulario

La lista es cerrada: estos prefijos y ninguno más. Sirven delante de cualquier utilidad del sistema, y también de las utilidades propias que se declaren en tu config.

Prefijo Cuándo vale Ejemplo
hover:El puntero está encima. Sólo en dispositivos que pueden pasar por encima: en una pantalla táctil no queda «pegado».hover:bg-gray-200
focus:El elemento tiene el foco, lo haya recibido por mouse o por teclado.focus:bg-gray-200
focus-visible:El foco llegó por teclado (o el navegador decide mostrarlo).focus-visible:underline
active:Mientras se está presionando.active:opacity-70
disabled:El elemento está deshabilitado: con el atributo disabled o con aria-disabled="true".disabled:opacity-50
checked:Una casilla o un radio marcado.checked:opacity-100
invalid:Un campo cuyo valor no pasa su validación.invalid:bg-danger-100
aria-<estado>:El atributo aria-<estado>="true". Los estados que valen: busy, checked, disabled, expanded, hidden, invalid, pressed, readonly, required y selected.aria-expanded:bg-gray-200
data-<nombre>:El elemento tiene el atributo data-<nombre> (sólo presencia, sin valor). El nombre va en minúsculas y no puede empezar con ts-.data-active:bg-gray-200
group-<estado>:Un ancestro marcado con group está en ese estado. Sirve cualquiera de los estados de arriba.group-hover:underline
peer-<estado>:Un hermano anterior marcado con peer está en ese estado.peer-checked:opacity-100
print:Al imprimir.print:hidden
sm: md: lg: xl:La pantalla tiene ese ancho o más. Los cortes son los de tus screens.md:flex
max-sm: max-md: max-lg: max-xl:La pantalla es más angosta que ese corte. Es lo contrario de sm: md: lg: xl: y usa los mismos cortes: md: vale desde 48rem y max-md: por debajo. Si se pisan, gana el corte más chico (max-sm: sobre max-md:).max-md:hidden
@sm: … @7xl:El contenedor marcado con cq tiene ese ancho o más: @sm 24rem, @md 28, @lg 32, @xl 36, @2xl 42, @3xl 48, @4xl 56, @5xl 64, @6xl 72 y @7xl 80rem.@2xl:flex

Los estados de pantalla y de contenedor se explican en Responsive. Aquí van los demás.


Deshabilitado, aria y data

disabled: vale tanto con el atributo disabled como con aria-disabled="true", así que sirve también para un enlace o un div que se comportan como botón. aria-expanded: y sus hermanos siguen un atributo que ya hay que poner por accesibilidad, y data-active: sigue un atributo tuyo: no hace falta escribir JavaScript para el estilo, sólo cambiar el atributo.

Botón deshabilitado

Con el puntero encima el fondo se oscurece, salvo en el botón deshabilitado, que mantiene el suyo.

html

Atributos de estado

El fondo sigue a aria-expanded y a data-active: al cambiar el atributo en el HTML, cambia el estilo.

Ana Torres (activa)
Bruno Díaz
html

group y peer

A veces un elemento tiene que reaccionar al estado de otro. Se marca el elemento que manda con group o peer, junto a la llave ts (class="ts group"), y el que reacciona usa group-hover:, peer-checked: y compañía. Las marcas no estilan nada por sí solas.

  • group va en un ancestro: reaccionan todos sus descendientes.
  • peer va en un hermano, y tiene que estar antes del que reacciona en el HTML. Es lo que permite, por ejemplo, mostrar algo según una casilla marcada sin escribir JavaScript.

group

El enlace de la derecha se subraya y se resalta cuando el puntero entra en cualquier parte de la fila.

html

peer

La casilla va primero; el texto que la sigue cambia cuando se marca.

html

Grupos con nombre

Cuando hay grupos dentro de grupos, conviene nombrar al que se quiere seguir: group/menu en el ancestro y group-hover/menu: en el que reacciona. Igual con peer/campo y peer-invalid/campo:. El nombre va en minúsculas, con letras, números y guiones.

html

Cadenas de variantes

Se pueden combinar hasta tres, siempre en este orden: pantalla o contenedor, después print:, después group- o peer-, y al final el estado del propio elemento. Una sola de cada tipo. Cada regla tiene así un único nombre.

Pantalla y estado

La tarjeta sólo reacciona al puntero desde las pantallas medianas.

html

Si se escriben fuera de orden (el estado antes de la pantalla, por ejemplo) la clase no se emite y taisho generate avisa con la forma correcta: «está fuera de orden y no se emite. ¿Se quiso decir …?». Lo mismo si la cadena tiene más de tres, repite un tipo o incluye un prefijo que no existe.

Imprimir

print: aplica sólo en la hoja impresa o en el PDF. Sirve para esconder lo que no tiene sentido en papel.

html

Variantes dentro de tus utilidades propias

Una utilidad propia de tu config (utilities) puede llevar las variantes adentro: cada entrada es variante:clase, con las mismas reglas de cadena de arriba. Así el botón completo, con su reposo, su puntero, su foco y su deshabilitado, queda en un solo nombre.

ts
svelte
  • Se validan al generar. Un prefijo que no existe, una cadena fuera de orden, un data-ts-* o una variante sobre un componente (hover:button) cortan taisho generate con un error que dice cuál es y, si hay una forma correcta, cuál.
  • El prefijo del uso se suma a la cadena de adentro. md:mi-boton con un hover: adentro reacciona al puntero sólo desde md. Si la suma no es una cadena válida (un lg: adentro y md: afuera, dos contextos) la clase no se emite y taisho generate y taisho check te avisan.
  • Una clase tuya en el mismo nivel la afina. Las reglas de tu utilidad van antes que las del sistema de su mismo nivel, así que hover:bg-gray-300 en el elemento gana sobre el hover:bg-gray-200 de adentro.
  • Entre dos utilidades propias va primero la que la otra compone, y después, la declarada antes.
  • Cuesta cero si no se usa. Con content sólo salen las reglas de las utilidades que tu código nombra.

Modificadores de tus utilidades propias

Una utilidad propia puede tener versiones: un botón destructive, uno outlined, uno que es las dos cosas. Se declaran como claves con punto (componente.modificador) y se usan sumando el modificador a la clase en el markup.

ts
svelte

Cómo se leen

  • La clave es el selector. 'mi-button.destructive.outlined' se emite como .mi-button:where(.destructive.outlined): vale cuando el elemento lleva las tres clases. El orden en que se escriben en el markup no importa.
  • Hay que declarar la utilidad antes. mi-button tiene que existir sin punto; los modificadores se cuelgan de ella.
  • Las entradas son las mismas de una utilidad. Clases con nombre corto, variantes (hover:, md:…) y otras utilidades propias lisas. Lo que no se puede componer es otro modificador ('x': ['mi-button.destructive'] da error): se compone mi-button y se pone destructive en el markup.
  • Cuesta cero si no se usa. La regla de un modificador sólo sale si tu código usa la utilidad y el modificador.

Combinaciones y cascada

Se declaran sólo las combinaciones que se ven distintas. Las que no se declaran no se inventan: el elemento recibe la base y los modificadores simples que lleve. Si se declara destructive.outlined, no hace falta declarar destructive ni outlined por separado.

  • El orden es base, simples, compuestos. Los tres pesan lo mismo (:where() no suma especificidad), así que gana el que va después: en mi-button destructive outlined el fondo y el color de destructive.outlined tapan a los de destructive y de outlined, y éstos a los de mi-button.
  • Una clase atómica en el markup afina. class="ts mi-button destructive bg-danger-900" pinta el fondo con bg-danger-900 y deja el resto del botón como está.
  • Los estados siguen la misma regla. El hover: de destructive.outlined tapa al de destructive.

Con una variante de pantalla

El prefijo va en la utilidad, no en el modificador: md:mi-button destructive. Un md:destructive no existe, porque cada modificador tendría que multiplicarse por cada contexto; taisho generate y taisho check te avisan:

text

Cómo se elige el nombre

Un modificador es una clase suelta en un elemento que ya lleva ts. Por eso no puede llamarse como algo que el sistema aplica solo.

  • No puede ser un nombre del sistema: ni un componente (link, card), ni una utilidad (flex, color-danger), ni compact. Tampoco ts, ni empezar con ts-, ni el nombre de otra utilidad tuya.
  • Sí puede ser un modificador de componente. Si link choca, se usa variant-link: fuera de un componente del sistema no hace nada, y se lee igual que el resto de las clases del sistema.
  • Sirven destructive, outlined, primary, ghost, soft…, porque no existen como clases sueltas del sistema.

Errores comunes

Se validan al generar, todos juntos, y cortan taisho generate.

  • «el componente "mi-button" no está en utilities». Se declaró 'mi-button.destructive' sin 'mi-button'. La base se declara primero, sin punto.
  • «tiene un modificador ("link") que choca con un nombre corto del sistema». Hay que cambiar el nombre. Con 'mi-button.variant-link' alcanza.
  • «es el nombre de otra utilidad propia». 'mi-button.card-hero' activaría card-hero. Conviene elegir otro nombre.
  • «tiene un modificador inválido». Minúsculas y dígitos separados por guiones, empezando con letra: Destructive se escribe destructive.
  • «repite la combinación» / «repite un modificador». a.b y b.a son lo mismo, y a.a no dice nada. Alcanza con una.
  • «un modificador no es una utilidad». Se compuso dentro de otra utilidad. Se compone la base y el modificador va en el markup.
  • «no hace nada sin ella en el mismo elemento». Es un aviso, no un error: se usó destructive en un elemento que no lleva mi-button. taisho check también lo marca.

Lo que no existe

El vocabulario es cerrado a propósito: así cada clase tiene un solo significado y se puede predecir.

No existe Qué hacer
dark:El modo oscuro lo resuelve el tema: los tokens cambian solos, sin una variante en cada clase. Ver Theming.
Valores arbitrarios, como hover:p-[13px], data-[open=true]: o aria-[sort=up]:El vocabulario es cerrado. Para un valor que no está, un token en tu config; para un atributo con valor, un data-<nombre> de presencia.
data-ts-<algo>:data-ts-* es el gancho de los componentes, no una variante. Tus atributos propios (data-active:) sí valen.
Otros estados y condiciones: first:, last:, odd:, even:, focus-within:, los rangos que combinan dos cortes en una clase (md:max-xl:) y los que empiezan con has-, not-, motion- o supports-Una clase propia en tu CSS, o el atributo que ya cambia en tu HTML con aria-<estado>: o data-<nombre>:.
Una variante sobre un componenteLos estados de un componente son suyos: sus modificadores (is-*), los atributos aria y sus partes internas. Las variantes valen sólo sobre utilidades, las del sistema y las tuyas.

Qué trae el CSS estático y qué hay que generar

Con el CSS que se carga desde el CDN (o desde taisho.full.css) no hay un paso de build, así que las variantes que vienen son una lista corta, la que más se usa en HTML escrito a mano:

  • hover: sobre los colores de escala (bg-, color-, border- y ring-, en todas las familias y tonos).
  • hover: sobre los colores semánticos (color-heading, color-copy, color-subtle, color-label, color-success, color-warning, color-info y color-danger).
  • hover: sobre underline, no-underline y opacity-*.
  • print:hidden y print:block.
  • Las variantes de pantalla (sm: … xl:; max-* sólo si el código la usa) de un conjunto curado y las de contenedor (@sm: … @xl:) de las grillas y la separación, que explica Responsive.

Todo lo demás (focus:, active:, disabled:, aria-…:, data-…:, group-…:, peer-…:, las cadenas y los contenedores desde @2xl:) lo escribe taisho generate cuando se usa. Se declara en content dónde buscar y cualquier utilidad con cualquier variante que aparezca escrita completa en tu código sale en el CSS; la que no se usa no pesa nada. Una variante que se arma en tiempo de ejecución no se puede leer del código: se pide en el safelist, con el nombre entero o como familia terminada en asterisco.

ts

Cómo se instala y se corre taisho generate está en Instalación.


Especificidad, en palabras simples

El CSS del sistema se ordena en seis capas, de menor a mayor prioridad: base, components, utilities, states, utility-states y print. Entre capas no cuenta la especificidad, cuenta la capa; dentro de una capa, gana la que se escribe después. Eso da un orden fácil de recordar:

  • Una utilidad le gana al reposo de un componente. ts button radius-full redondea y ts button bg-danger-700 pinta de rojo, aunque el botón traiga su propio radio y su propio fondo.
  • Una utilidad no pisa los estados del componente. Ese botón rojo sigue cambiando con el puntero (pasa al tono siguiente de su color), conserva el aro de foco y, deshabilitado, sigue gris. Para cambiar un estado se usa su variante: hover:bg-success-500.
  • El texto acompaña al fondo, salvo que se pida un color. hover:bg-success-500 pone también el color de contraste de ese fondo, y lo mismo hacen focus-visible:, group-hover: y las demás variantes de estado de bg-*. Un color-* escrito en el elemento gana, también en hover y active, y un hover:color-* gana al contraste de hover:bg-*. En disabled, checked, selected, invalid y open manda el estado del componente.
  • Un estado le gana a la clase común. Si un elemento tiene bg-gray-100 y hover:bg-gray-200, con el puntero encima manda el segundo, sin importar el orden en que se escribieron las clases.
  • Un estado le gana a una pantalla. Si coinciden md:p-double y hover:p-base, manda el de hover.
  • Pantalla más estado le gana al estado solo. md:hover:bg-gray-300 pisa a hover:bg-gray-200 desde md.
  • Entre estados sin pantalla, disabled: manda. Un botón deshabilitado con el puntero encima conserva lo que dice disabled:.
  • group-…: y peer-…: pesan igual que los estados propios, y si coinciden gana el estado propio.
  • print: va al final de todo: en papel gana sobre la clase común, sobre las pantallas y sobre los estados. Un botón con hover:bg-gray-200 y print:hidden se oculta al imprimir aunque el puntero esté encima.

Tu CSS

Una regla tuya con una sola clase, escrita dentro de la capa utilities, no le gana a un estado. Si se escribe tu CSS sin capa, le gana siempre.

Consejos

  • No hay que esconder información detrás de un hover. En una pantalla táctil no hay puntero y quien navega con teclado tampoco lo usa. Lo importante debe quedar visible y la variante sirve para reforzar, como en el ejemplo de group.
  • Para el foco por teclado, focus-visible:. focus: también se activa al hacer clic con el mouse.
  • Si el estado ya existe como atributo, se sigue ese atributo. aria-expanded: mantiene el estilo y la accesibilidad sincronizados con una sola fuente.