Tokens de diseño

Los tokens de diseño son nombres que representan decisiones visuales del sistema, como colores, tipografías, espacios, bordes y sombras. En lugar de repetir un valor específico en cada pantalla o componente, los equipos utilizan una referencia común que puede actualizarse de manera centralizada.

Esta capa compartida conecta el trabajo de diseño y desarrollo. Ayuda a mantener la coherencia entre productos, reduce decisiones arbitrarias y permite que los cambios del sistema se propaguen de forma controlada a diferentes plataformas.

Por ejemplo, en vez de definir directamente un color hexadecimal para un texto secundario, se utiliza el token semántico --color-text-base-subtle. El nombre explica el propósito del valor y permite modificar su apariencia sin cambiar la intención con que fue aplicado.

En el Framework Kit de Gobierno los tokens se distribuyen como custom properties de CSS en el paquete @gobdigital-cl/vanilla, disponibles al importar su hoja de estilos.

Cómo se organizan

Los tokens se estructuran en niveles para separar los valores de origen de las decisiones de uso.

Siempre que exista un token semántico, úsalo antes que un valor base. Esto permite conservar el significado y adaptar la apariencia del sistema sin modificar cada implementación.

Los tokens con prefijo legacy corresponden a decisiones anteriores del sistema. No los utilices en desarrollos nuevos: están disponibles solo para facilitar la migración de productos existentes.

Categorías

Color

Los tokens de color se derivan de las paletas documentadas en Color, organizadas en escalas de peso de 0 a 1000: Brand, Blue, Navy Blue, Green, Red, Yellow, Violet, Pink, Neutral, Dark Neutral y sus variantes con opacidad.

Sobre esas escalas se definen tokens semánticos según la función del color en la interfaz:

Espaciado

La escala de espaciado es numérica y se construye sobre la unidad base de 4 píxeles descrita en Espaciado:

--spacing-1  --spacing-2  --spacing-3  --spacing-4
--spacing-5  --spacing-6  --spacing-7

Bordes

El radio de las esquinas usa una escala nominal de tres pasos:

--radius-s  --radius-m  --radius-l

Tipografía

Los pesos tipográficos se exponen como tokens independientes, por ejemplo --font-weight-bold. Los tamaños y jerarquías se aplican mediante las clases de la escala documentada en Tipografía.

La colección completa de tokens vive en el paquete @gobdigital-cl/vanilla. Los ejemplos de esta página corresponden a tokens en uso y no constituyen el listado exhaustivo.

Nomenclatura

Los tokens se declaran como custom properties de CSS en kebab-case, comunicando desde lo general hacia lo específico. Una estructura predecible facilita la búsqueda en Figma y permite reconocer la misma decisión en código.

--categoría-propiedad-contexto-variante

Por ejemplo:

--color-text-base-subtle
--color-border-default-tertiary
--color-background-container-container-subtle
--spacing-4
--radius-m

Evita nombres asociados a una apariencia puntual, como azul-claro o espacio-grande, cuando el valor tenga una función concreta. Los nombres semánticos resisten mejor los cambios de tema, marca o contexto.

Uso en diseño

En Figma, aplica las variables y estilos publicados por la librería de UI Pacífico. No desvincules los estilos ni crees valores locales si ya existe un token que cumple el mismo propósito.

• Revisa la función del token antes de elegirlo por su apariencia.
• Usa variables semánticas para construir componentes y pantallas.
• Mantén vinculadas las instancias a la librería para recibir actualizaciones.
• Documenta los casos que no estén cubiertos antes de crear un valor nuevo.

Uso en código

En desarrollo, los tokens se consumen como variables CSS y evitan incorporar valores visuales de forma directa en los componentes. Están disponibles al importar la hoja de estilos del framework:

import '@gobdigital-cl/vanilla/styles.css'

Una vez cargada, aplica los tokens con var():

.ejemplo {
  padding: var(--spacing-4);
  border: 1px solid var(--color-border-base-subtle);
  border-radius: var(--radius-m);
  color: var(--color-text-base-subtle);
}

Cuando un token pueda no estar definido en el contexto de uso, declara un valor de respaldo como segundo argumento:

.ejemplo:focus-visible {
  outline: 3px solid var(--color-legacy-border-focus-default, #ffdd00);
}

Usar las variables oficiales mantiene la correspondencia con Figma y permite actualizar el sistema sin buscar y reemplazar valores en cada producto.

Buenas prácticas

Cambios y versiones

Las modificaciones en los tokens pueden afectar varios componentes y productos al mismo tiempo. Antes de publicar un cambio, revisa su impacto, documenta la actualización y comunica si requiere ajustes por parte de los equipos consumidores.

Cuando un token deje de utilizarse, debe marcarse como obsoleto antes de eliminarlo. Siempre que sea posible, indica el token que lo reemplaza y define un periodo de transición para facilitar la actualización.