La tabla de anatomía

Antes de dibujar un componente o de programarlo, DesignToken101 escribe una tabla: qué token lleva cada parte en cada estado. Es el puente entre Figma y el código, y la puedes hacer entera sin salir de Figma. En esta lección verás cómo se escribe, cómo se lee con dos ejemplos reales y por qué conviene escribirla primero.

En esta página

• Parte, estado y token
• La tabla de Button
• La tabla de Callout
• Cada celda tiene su contraste
• Primero la tabla
• El método del módulo
• Lo que te llevas

Parte, estado y token

La tabla tiene tres ingredientes:

• Las partes del componente, una por fila: el fondo, el borde, el texto, el icono, el anillo de foco, el radio.
• Los estados o las variantes, uno por columna: default, hover, active y focus en un control; note, warning… en un aviso.
• Un token en cada celda, siempre un semántico. Si una parte no tiene nada en un estado, la celda lo dice ("Sin fondo"); si repite el valor de la columna anterior, lleva una flecha (←).

La tabla de Button

Esta es la tabla de la variante primary del Button de DesignToken101:

Y la de secondary:

Fíjate en tres cosas:

• En primary, el texto es el mismo en los cuatro estados: lo que cambia es el fondo. En secondary, el fondo no existe en default y aparece con el puntero.
• El estado focus repite el fondo de default y añade el anillo. El foco se marca con el anillo, no con otro color.
• Los tokens de estado ya existían en el sistema (…/hover, …/active): los viste en Estados. El componente no inventa ninguno.
• El borde del primary es transparente en código y lleva la variable del fondo en Figma: no se ve, pero hace visible el botón con los colores forzados del sistema. Lo verás en Un borde para los colores forzados.

La tabla de Callout

En un componente sin estados, las columnas son las variantes. Esta es la tabla del Callout:

Cada variante usa los tokens de un rol (info, warning, accent, neutral). La tabla deja ver de un vistazo que el contenido no cambia de color: lo que distingue un aviso de otro es el fondo, el borde, el icono y la etiqueta.

const VARIANTS: Record<CalloutVariant, { icon: LucideIcon; box: string; role: string }> = {
  note: { icon: Info, box: 'bg-info-subtle border-info-default', role: 'text-info-default' },
  warning: { icon: TriangleAlert, box: 'bg-warning-subtle border-warning-default', role: 'text-warning-default' },
  recommendation: { icon: ThumbsUp, box: 'bg-accent-subtle border-accent-default', role: 'text-accent-default' },
  pending: { icon: ClockAlert, box: 'bg-neutral-subtle border-neutral-default', role: 'text-neutral-subtle' },
};

Cada celda tiene su contraste

Cada celda de texto o de icono forma un par con el fondo de su misma columna. Por eso la tabla de anatomía de DesignToken101 lleva debajo el contraste de cada par, en Light y en Dark. En el Button, el texto da 9,63:1 en default (en los dos modos) en primary, y 17,79:1 en Light y 18,89:1 en Dark en secondary.

Los pares de un componente salen de tu tabla de pares del módulo 7: si una celda usa un par que ya comprobaste, no tienes que volver a calcularlo. Si usa uno nuevo (un texto sobre un fondo de estado, por ejemplo), lo añades a la tabla.

Hay celdas que no necesitan 3:1. El fondo del primary frente a la página da 2,05:1 en Light, y está permitido: según la guía de 1.4.11, si un control tiene un contenido visible que lo identifica, como su texto, no hace falta que su borde contraste (Understanding 1.4.11). Lo viste en Qué no necesita 3:1.

Primero la tabla

Así aparecieron en DesignToken101 los tokens de estado: al preguntarse qué pasaba con cada control en hover y active, el sistema no tenía tokens para ello, y se añadieron con su contraste calculado. La tabla sirve también de documentación: es lo que verá quien implemente el componente, con o sin acceso a Figma. Puede vivir en la página de documentación de tu sistema (Documentar el sistema).

El método del módulo

Todo el módulo sigue el mismo orden, y el ejercicio también:

Fuentes

• Understanding 1.4.11 Non-text Contrast