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.
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.
Atributos de estado
El fondo sigue a aria-expanded y a data-active: al cambiar el atributo en el HTML, cambia el estilo.
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.
groupva en un ancestro: reaccionan todos sus descendientes.peerva 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.
peer
La casilla va primero; el texto que la sigue cambia cuando se marca.
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.
<div class="ts group/proyecto p-base radius-lg bg-gray-100">
<p>Data pipeline</p>
<ul>
<li class="ts group/miembro hover:bg-gray-200">
<span>Carla Ruiz</span>
<span class="ts color-subtle group-hover/proyecto:underline">Responsable del proyecto</span>
<span class="ts color-subtle group-hover/miembro:underline">Quitar</span>
</li>
</ul>
</div>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.
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.
<button type="button" class="ts px-base py-half radius-md bg-gray-200 print:hidden">
Descargar informe
</button>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.
// taisho.config.ts
utilities: {
'mi-boton': [
'p-base', 'radius-lg', 'bg-gray-100',
'hover:bg-gray-200',
'focus-visible:bg-gray-200',
'disabled:opacity-50',
'md:p-double',
],
},<button type="button" class="ts mi-boton">Guardar</button>
<button type="button" class="ts mi-boton hover:bg-gray-300">Guardar y cerrar</button>- 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) cortantaisho generatecon 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-botoncon unhover:adentro reacciona al puntero sólo desdemd. Si la suma no es una cadena válida (unlg:adentro ymd:afuera, dos contextos) la clase no se emite ytaisho generateytaisho checkte 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-300en el elemento gana sobre elhover:bg-gray-200de 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
contentsó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.
// taisho.config.ts
utilities: {
'mi-button': ['p-half', 'radius-full', 'bg-brand-700', 'color-brand-100', 'hover:bg-brand-800'],
'mi-button.destructive': ['bg-danger-700', 'hover:bg-danger-800'],
'mi-button.outlined': ['bg-transparent', 'color-brand-700', 'hover:bg-brand-100'],
'mi-button.destructive.outlined': ['bg-transparent', 'color-danger-700', 'hover:bg-danger-100'],
},<button class="ts mi-button">Guardar</button>
<button class="ts mi-button destructive">Borrar</button>
<button class="ts mi-button outlined">Cancelar</button>
<button class="ts mi-button destructive outlined">Borrar</button>
<button class="ts md:mi-button destructive">Borrar desde md</button>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-buttontiene 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 componemi-buttony se ponedestructiveen 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: enmi-button destructive outlinedel fondo y el color dedestructive.outlinedtapan a los dedestructivey deoutlined, y éstos a los demi-button. - Una clase atómica en el markup afina.
class="ts mi-button destructive bg-danger-900"pinta el fondo conbg-danger-900y deja el resto del botón como está. - Los estados siguen la misma regla. El
hover:dedestructive.outlinedtapa al dedestructive.
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:
"md:destructive" no se emite: "destructive" es un modificador de "mi-button" y no lleva variante; se pone la variante en la propia (p. ej. "md:mi-button").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), nicompact. Tampocots, ni empezar conts-, ni el nombre de otra utilidad tuya. - Sí puede ser un modificador de componente. Si
linkchoca, se usavariant-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íacard-hero. Conviene elegir otro nombre. - «tiene un modificador inválido». Minúsculas y dígitos separados por
guiones, empezando con letra:
Destructivese escribedestructive. - «repite la combinación» / «repite un modificador».
a.byb.ason lo mismo, ya.ano 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ó
destructiveen un elemento que no llevami-button.taisho checktambié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 componente | Los 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.
// taisho.config.ts (fragmento)
content: ['**/*.{html,svelte,vue,astro,jsx,tsx,js,ts,css}'],
safelist: ['md:hover:bg-gray-200', 'hover:bg-gray-*'],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-fullredondea yts button bg-danger-700pinta 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-500pone también el color de contraste de ese fondo, y lo mismo hacenfocus-visible:,group-hover:y las demás variantes de estado debg-*. Uncolor-*escrito en el elemento gana, también en hover y active, y unhover:color-*gana al contraste dehover:bg-*. Endisabled,checked,selected,invalidyopenmanda el estado del componente. - Un estado le gana a la clase común. Si un elemento tiene
bg-gray-100yhover: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-doubleyhover:p-base, manda el de hover. - Pantalla más estado le gana al estado solo.
md:hover:bg-gray-300pisa ahover:bg-gray-200desdemd. - Entre estados sin pantalla,
disabled:manda. Un botón deshabilitado con el puntero encima conserva lo que dicedisabled:. group-…:ypeer-…: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 conhover:bg-gray-200yprint:hiddense oculta al imprimir aunque el puntero esté encima.
Tu CSS
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.