La convención de DesignToken101

Una convención de nombres es un documento corto: un orden de niveles, unas reglas y una lista de palabras permitidas en cada nivel. En esta lección verás la de DesignToken101 completa, con el motivo de cada regla. Es la que seguirás, o adaptarás, en el ejercicio del módulo.

En esta página

• El orden de los niveles
• Las reglas
• El vocabulario
• Las paletas se nombran por su tono
• Los semánticos de tamaño
• Los tokens de componente
• Cómo queda en el archivo
• Lo que te llevas

El orden de los niveles

Los semánticos de color de DesignToken101 siguen siempre este orden (los de tamaño tienen el suyo, que verás más abajo):

categoría / propiedad / rol / énfasis / estado

El orden no cambia nunca. Un nivel puede faltar (regla 3), pero los que están aparecen siempre en el mismo sitio. Así, quien ve …/strong/hover sabe que strong es el énfasis y hover el estado, sin tener que adivinarlo.

Las reglas

La especificación del sistema tiene siete reglas. Cinco son sobre la forma del nombre; las otras dos tienen lección propia o ya las has visto.

1. Minúsculas y palabras completas, separadas por guiones dentro de cada nivel (on-accent, max-width). Nada de abreviaturas: background, no bg. El curso de Figma lo aconseja porque una abreviatura se puede interpretar de varias formas (Figma: Update 1). Sin valores ni temas en el nombre, con la excepción de los pesos tipográficos (font-weight/600).
2. / separa los niveles en Figma. Al exportar, cada / es un grupo de DTCG; en CSS, un guion. Lo verás en Un nombre en Figma, DTCG y CSS.
3. Orden fijo, sin niveles de relleno. Un nivel que no aporta información no se escribe (Anatomía de un nombre).
4. Hoja explícita. Si un nombre fuera a la vez token y grupo, el token lleva /default. Tiene lección propia: Estados en el nombre.
5. Primitivos: categoría / paleta / paso, con las paletas nombradas por su tono, nunca por su rol. Lo retomas más abajo.
6. Los semánticos son alias, con un máximo de dos saltos. Lo viste en el módulo 3, con sus excepciones (Cuando un semántico no es alias).
7. Pares on- para el texto sobre un fondo de color fuerte, con su contraste comprobado (Los pares on).

El vocabulario

Cada nivel admite una lista cerrada de palabras. Si una palabra no está en la lista, no se usa hasta que se añade a la convención.

Cuatro de esas elecciones merecen una explicación:

• danger y no error. Es la palabra que usa el SDS de Figma (--sds-color-text-danger-default, SDS: theme.css), y la que usa Atlassian al hablar del botón de una acción peligrosa (Atlassian: Design tokens).
• focus y overlay en el lugar del rol. El anillo de foco y la capa que oscurece la página tras el panel móvil no cambian con el rol: son los mismos en toda la interfaz. Por eso no llevan un rol de color delante, sino que ocupan su lugar. Es el mismo criterio que seguiría disabled (lo verás en Estados en el nombre). Atlassian pone su token de foco en la misma posición, justo después de la propiedad: color.border.focused (Atlassian: Design tokens, lista completa).
• Sin propiedad icon. Atlassian sí la tiene (color.icon.success). DesignToken101 la descartó: en esta web, los iconos usan el token de texto de su contexto. Los tokens de texto llevan el scope de forma para poder colorear iconos (Un scope por propiedad). Si un día hace falta separarlos, se añade icon sin romper nada.
• active es "pulsado". Es el estado mientras se pulsa un control, como la pseudoclase :active de CSS (MDN: :active). Por eso la variante que marca la sección actual del sidebar se llama current y no active: con active, el mismo nombre significaría dos cosas.

Las paletas se nombran por su tono

En el módulo 2 viste que las paletas primitivas se nombran por su tono (emerald, red, amber, blue) o por su naturaleza (neutral), nunca por su rol (El nombre dice qué valor es). Con la convención completa se ve por qué esa regla importa: el rol ya tiene su sitio, y es el nombre semántico.

Si la paleta del acento se llamara brand, el token de éxito apuntaría a brand/700. El nombre diría que el éxito es "de marca", que no es lo que significa. Con los nombres por tono, cada capa dice una cosa: el primitivo, qué color es; el semántico, para qué se usa.

Los semánticos de tamaño

Los semánticos de la colección Semantic size no tienen propiedad, rol ni énfasis: se aplican siempre a la misma propiedad y no tienen variantes de color. Siguen otro orden, categoría / elemento / medida, con los niveles necesarios:

El elemento dice a qué se aplica: a un control o a un contenedor, en el radio; a una zona de la página, en las medidas de maquetación. La medida usa el nombre de la propiedad CSS en la que se aplica. El radio no la necesita: siempre es el de las esquinas.

La categoría size agrupa las medidas de maquetación que no son espaciado ni radio.

size/sidebar/width es un buen ejemplo de cómo aparece un token: el sidebar se dibujó en Figma a 305 px sin variable, y el hueco se vio al llevarlo a código. Se decidió un valor, 304 px, y se creó el token con un nombre que encajaba en la categoría que ya existía.

Los tokens de componente

DesignToken101 no tiene tokens de componente (La capa de componente). Aun así, conviene decidir cómo se nombrarían, para que el primero no invente su propio patrón.

El curso de Figma propone este orden: componente, tipo, propiedad y estado. Su ejemplo es button-primary-background-default (Figma: Update 1).

Un token de componente apunta siempre a un semántico, nunca a un primitivo (La capa de componente).

Cómo queda en el archivo

Como cada nivel es un grupo, el orden de los niveles es el orden de los grupos. Esta es la estructura de la colección Semantic color en el archivo que exporta Figma (tokens/figma/semantic-color/Light.tokens.json), con los tokens de cada grupo entre paréntesis:

color
├── background   (overlay)
│   ├── neutral  (default, subtle, strong, hover, active, translucent)
│   ├── accent   (subtle)
│   │   └── strong  (default, hover, active)
│   └── info, success, warning, danger  (subtle)
├── text         (on-accent)
│   ├── neutral  (default, subtle)
│   ├── accent   (default, hover)
│   └── info, success, warning, danger  (default)
└── border       (focus)
    ├── neutral  (default, strong)
    ├── accent   (default, strong)
    └── info, success, warning, danger  (default)

Todos los fondos quedan bajo background; todos los textos, bajo text. El orden del nombre ordena también el archivo.

Fuentes

• Figma: Update 1, Tokens, variables, and styles
• Figma: Simple Design System, theme.css
• Atlassian Design System: Design tokens y su lista completa de tokens
• MDN: :active