Design Tokens

Los design tokens son propiedades personalizadas de CSS con nombre: valores de color, tamaños, cualquier cosa que una hoja de estilos pueda consumir: almacenados en la base de datos y convertidos en declaraciones :root en cada página construida. Cambia el valor del token en el admin, reconstruye, y cada regla de hoja de estilos que referencie esa variable se actualiza en todo el site. Sin ediciones de templates, sin código.

Esta página explica la pantalla de Design Tokens, cómo llegan los tokens a las páginas construidas, y cómo nombrar bien las cosas.

La pantalla de Design Tokens

Bajo Design Tokens en la barra lateral (Administradores y usuarios cuyos tipos de contenido permitidos incluyen design tokens):

• La lista muestra cada token ordenado por su Group opcional y luego por nombre, cada fila llevando el nombre, el valor actual, la etiqueta de grupo y la hora de última actualización.
• + New Token inicia una entrada nueva.

Crear o editar un token

Tres campos:

• Name: el identificador de la variable CSS sin los guiones iniciales. Debe empezar con una letra y contener solo letras, dígitos, guiones y guiones bajos (las reglas de CSS rechazan cualquier otra cosa, incluido un guion inicial). Ejemplo: accent-color.
• Value: exactamente lo que debe ser la variable CSS: un color (#FAF7F2), un espaciado (1.25rem), o incluso una referencia a otra variable.
• Group: una etiqueta organizacional opcional (colors, mostrada como placeholder); ordena la lista, pero es puramente organizacional y no tiene ningún efecto sobre el CSS construido.

Reglas que aplica el formulario:

• Los nombres deben empezar con una letra.
• Los nombres son únicos en todo el site: dos tokens con el mismo identificador es un error; edita el existente en su lugar.
• Los valores existentes quedan exactamente como están hasta que los cambies (el formulario viene pre-llenado).

En qué se convierte un token en el site construido

En tiempo de build, cada token se convierte en una propiedad personalizada de CSS. Un token llamado accent-color con el valor #AA2266 se convierte en:

:root {
  --accent-color: #AA2266;
}

y aparece en el <head> de cada página construida (se añade un único bloque de estilo solo cuando existe al menos un token). La hoja de estilos de tu theme: o la del theme integrado: la referencia como var(--accent-color) dondequiera que se usen esos valores.

Esto significa:

• Para recolorear un theme sin tocar sus templates: crea tokens que coincidan con los nombres de variable que su hoja de estilos ya usa: estás cambiando los valores de las propiedades personalizadas debajo del diseño, no las reglas del diseño.
• La salida está completamente calificada: los valores son cadenas CSS completas, sin validación, sin coerción de tipo: un token usado como color solo se comporta como color donde la hoja de estilos espera un color.
• Tanto los nombres como los valores se escapan en HTML en la hoja de estilos emitida, así que no hay ruta de inyección.

Cambiar un token

Edita el valor del token y guarda: pero el site no se reconstruye por sí solo: los tokens no están ligados a rebuilds automáticos. Despacha un build (dashboard o programado) y la siguiente pasada escribe el nuevo valor en cada página. Los endpoints de preview comparten la misma consulta de tokens: las previews reflejan los valores actualizados incluso mientras el site en vivo aún no se ha reconstruido.

Eliminar un token

La eliminación es inmediata: sin fase de trash, sin restauración. En el siguiente build la propiedad personalizada simplemente deja de emitirse. Las reglas de hoja de estilos que la referenciaban hacen fallback a sus propios valores por defecto, ya que la variable ya no existe en los lugares donde se usaba. Si el objetivo era un cambio de color, normalmente es mejor actualizar el valor del token existente que eliminar y recrear.

La distinción y con qué no confundir

• Nombres de token → nombres de variable CSS: sin el guion inicial al momento de la definición; el builder añade el prefijo CSS --.
• Las etiquetas de grupo son para ti, no para la hoja de estilos: ayudan a ordenar la lista, y no cambian el CSS.
• Los tokens no pueden hacer shadow de tipos de site. No puedes crear un token que no sea un color o una longitud y que se comporte como tal; los tokens son pares nombre → valor, nada más que referencias CSS.

La versión corta

Define un nombre (una variable CSS, sin los guiones) y un valor en la pantalla de Design Tokens; el build escribe un bloque :root con todos los tokens en cada página: y las hojas de estilos del theme responden a las referencias de las variables como colores, espaciados o cualquier otra cosa sin una revisión de la template.