Variables CSS

Variables CSS del VTEX Style

En archivos css, scss, less y postcss la extensión autocompleta las CSS custom properties que VTEX expone en runtime a partir de tu JSON de tokens — el mismo formato del style.json nativo:

.container {
  padding: var(--spacing-4);
  font-size: var(--type-scale-3);
  color: var(--text-action-primary);
}

Con el tokens.json por defecto que viene embebido son 251 variables, de las cuales 184 son colores.

Cómo se comporta

• Se dispara al escribir - o (.
• Si el cursor ya está dentro de un var( sin cerrar en la misma línea, inserta sólo el nombre. Si no, inserta el var(--nombre) completo.
• Las variables de color se ofrecen como Color, con su swatch y el valor a la vista. Las demás, como Variable, con el valor en el detalle.
• El rango que la sugerencia reemplaza incluye los guiones ya tecleados, para que escribir --ty y aceptar no te deje ----type-scale-1.

De dónde salen los tokens

Por prioridad, y se queda con el primero que exista:

1. styles/configs/tokens.json del workspace.
2. tokens.json en la raíz del workspace.
3. El assets/tokens.json embebido en la extensión, con los valores por defecto de VTEX.

Cualquier tokens.json del workspace queda vigilado: al crearlo, cambiarlo o borrarlo, la lista se recarga sola.

Un JSON inválido no rompe nada. Si el archivo elegido no se puede leer o no parsea, la extensión conserva los tokens que ya tenía cargados en vez de dejarte sin autocompletado a mitad de una edición. Sólo cae al default embebido si todavía no había cargado ninguno.

Las reglas de nombre

Son las mismas que aplica VTEX al generar las custom properties. Cambiar una de estas reglas es cambiar el contrato con la plataforma:

entrada del JSON	variable generada	valor
typeScale[0]	--type-scale-1	{v}rem
spacing[2]	--spacing-2	{v}rem
borderWidths[i]	--border-width-{i}	{v}rem, y 0 se queda en "0"
borderRadius[i]	--border-radius-{i}	{v}rem, y 0 se queda en "0"
widths[0]	--width-1	{v}rem
maxWidths[0]	--max-width-1	{v}rem
heights[0]	--height-1	{v}rem
sizes[].name	--size-{name}	{v}rem
opacity	--opacity-{n}	el valor crudo, sin rem
typography.measure	--measure, --measure-wide, --measure-narrow	{v}em
colors[k]	--{k}	el color
semanticColors[g][k]	--{g}-{k}	el color

Dos detalles que se ven poco y se notan mucho:

• En opacity, el número del nombre se deriva del valor, no del índice. Acepta tanto array como objeto.
• En semanticColors el nombre se concatena literal, así que los modificadores de la clave pasan intactos: --text-action-primary--faded, --text-action-primary--inverted.

Las secciones que no estén en tu JSON simplemente no generan nada. Una entrada vacía o inválida devuelve una lista vacía sin lanzar.

Exportar el :root

El comando VTEX: Gerar tokens.css recorre el mismo generador y escribe un archivo tokens.css al lado del JSON de origen:

:root {
  --type-scale-1: 3rem;
  --spacing-0: 0rem;
  --emphasis: #F71963;
  ...
}

Sirve para tener las variables a mano fuera del runtime de VTEX: Storybook, una página suelta, un test visual. Al terminar te abre el archivo generado y te dice cuántas variables escribió. Ver Comandos.