Cómo nombrar los tokens de tipografía (display, heading, body, caption)

Nombra los tokens de tipografía según el rol que cumple el texto — display, heading-lg, body-md, caption — nunca según sus valores (font-24) ni según los elementos HTML a los que dan estilo (h2-size). Los nombres basados en valores quedan obsoletos en cuanto reajustas la escala, y los nombres basados en elementos acoplan el estilo visual al marcado del documento, que son dos decisiones distintas. Un nombre de rol expresa lo único del token que se pretende que siga siendo cierto: qué trabajo hace ese texto.

La segunda mitad de la regla es igual de importante: un token de tipografía es compuesto. El tamaño, el interlineado, el grosor y el espaciado entre letras viajan juntos bajo el nombre de rol — un body-md que solo lleva un tamaño no es un estilo, es un número. Este artículo cubre ambas mitades, la convención de tallas de camiseta que mantiene pequeños los conjuntos de roles, y la ruta de exportación que lleva los nombres a CSS, Tailwind y Figma. Forma parte de nuestra guía de escala tipográfica.

¿Por qué no nombrar los tokens según los valores?

Porque los valores son la parte del sistema diseñada para cambiar. Supón que tu escala genera un tamaño de encabezado de 24px y nombras el token font-24. El trimestre siguiente ajustas la razón de 1,25 a 1,333 y ese paso ahora calcula 25px. Tus opciones son ambas malas: renombrar el token en todos los lugares donde se usa — un cambio disruptivo en cada hoja de estilos, componente y archivo de diseño que lo referencia — o mantener un token llamado font-24 cuyo valor es 25, lo cual es peor, porque ahora el nombre miente activamente.

Un nombre de rol sobrevive al reajuste sin tocarse. heading-md puede pasar de 24px a 25px y cada uso sigue siendo correcto, porque el nombre nunca reclamó un valor — reclamó un trabajo, y el trabajo no cambió. Es el mismo razonamiento que aleja a los sistemas de color de nombres como blue-500 para los espacios semánticos: nombra la decisión, no la respuesta actual.

¿Por qué no nombrar los tokens según los elementos?

h2-size parece inofensivo — hasta que el estilo y el marcado necesitan discrepar, algo que en productos reales ocurre constantemente. Los niveles de encabezado en HTML expresan la estructura del documento: un h2 es «una sección un nivel por debajo de un h1», un hecho del que dependen los lectores de pantalla y los esquemas. El rango visual es una decisión aparte. El título de una tarjeta podría ser un h3 en el panel y un h2 en su propia página mientras se ve idéntico en ambos lugares; una página legal podría tener seis niveles de estructura pero solo tres niveles de diferenciación visual.

Los tokens nombrados según el elemento fuerzan una elección entre dos modos de fallo: elegir el elemento por su apariencia (esquema incorrecto, un coste de accesibilidad) o elegirlo por la estructura y obtener el estilo equivocado. Los tokens nombrados según el rol disuelven el conflicto — cualquier elemento puede llevar heading-md, y el esquema del documento sigue siendo una decisión independiente y semántica.

¿Qué contiene realmente un token de tipografía?

Un estilo de texto completo. Las propiedades de un estilo de texto se afinan como una unidad: un encabezado de 28px recibe su interlineado de 36px porque mide 28px, su grosor de 600 porque los encabezados se jerarquizan por oscuridad, su espaciado entre letras de −0,01em porque el espaciado integrado de la fuente se lee suelto a medida que crecen los tamaños. Aplica el tamaño sin lo demás y no habrás aplicado el estilo — habrás aplicado un fragmento y dejado las otras tres propiedades a lo que el contexto herede por casualidad.

Por eso el formato de tokens DTCG define typography como un tipo compuesto: un solo token cuyo valor es el paquete entero — familia, tamaño, grosor, interlineado, espaciado entre letras — en lugar de cinco tokens sueltos que esperan usarse juntos.

¿Cómo funciona la convención de tallas dentro del rol?

La mayoría de los sistemas se decantan por un nombre de dos partes: primero la familia de rol y, en segundo lugar, una talla de camiseta dentro del rol — body-sm, body-md, body-lg. Las familias son pocas y estables: display en lo más alto, una serie de tamaños heading, una serie de tamaños body, y los pequeños roles utilitarios — caption y overline — al final. El sufijo de talla absorbe el crecimiento: cuando un diseño necesita de verdad un estilo de body más grande, body-lg aparece sin renombrar nada de lo que ya existe.

Dos convenciones mantienen honestos los conjuntos. Los roles que aparecen una sola vez no reciben sufijo — caption en lugar de caption-md — hasta que exista de verdad una segunda variante. Y display se sitúa por encima de la serie de encabezados como su propia familia, en lugar de como heading-xl, porque su trabajo (una declaración protagonista que se lee de un vistazo) difiere del trabajo de un encabezado (orientación), y sus propiedades — interlineado más ajustado, tracking más ajustado — rompen el patrón de los encabezados en vez de extenderlo.

¿Cómo se ve un conjunto de roles completo?

Aquí tienes un conjunto trabajado, generado a partir de una base de 16px con razón 1,333 con dos notas por intervalo, con los interlineados ajustados a la rejilla de línea base de 8px (la mitad de la base) y la familia de fuente omitida por brevedad:

{
  "type": {
    "display":    { "$type": "typography", "$value":
      { "fontSize": "51px", "lineHeight": "56px", "fontWeight": 700, "letterSpacing": "-0.02em" } },
    "heading-lg": { "$type": "typography", "$value":
      { "fontSize": "38px", "lineHeight": "48px", "fontWeight": 700, "letterSpacing": "-0.015em" } },
    "heading-md": { "$type": "typography", "$value":
      { "fontSize": "28px", "lineHeight": "36px", "fontWeight": 600, "letterSpacing": "-0.01em" } },
    "heading-sm": { "$type": "typography", "$value":
      { "fontSize": "21px", "lineHeight": "28px", "fontWeight": 600, "letterSpacing": "0em" } },
    "body-lg":    { "$type": "typography", "$value":
      { "fontSize": "18px", "lineHeight": "28px", "fontWeight": 400, "letterSpacing": "0em" } },
    "body-md":    { "$type": "typography", "$value":
      { "fontSize": "16px", "lineHeight": "24px", "fontWeight": 400, "letterSpacing": "0em" } },
    "body-sm":    { "$type": "typography", "$value":
      { "fontSize": "14px", "lineHeight": "20px", "fontWeight": 400, "letterSpacing": "0em" } },
    "caption":    { "$type": "typography", "$value":
      { "fontSize": "12px", "lineHeight": "16px", "fontWeight": 400, "letterSpacing": "0.02em" } },
    "overline":   { "$type": "typography", "$value":
      { "fontSize": "12px", "lineHeight": "16px", "fontWeight": 500, "letterSpacing": "0.08em" } }
  }
}

Cada tamaño se asienta en la escala, cada interlineado es un múltiplo de la línea base de 8px, y cada token se lee como un estilo completo — quien revisa puede ver de un vistazo que los tamaños pequeños ganan grosor y tracking mientras que los tamaños grandes pierden ambos.

Esta es la forma que Scale Composer ensambla a medida que asignas pasos de escala a roles: abre la exportación de tokens de esta escala — los niveles semánticos desde caption hasta display, cada uno reunido con su tamaño, interlineado, grosor y espaciado entre letras bajo su nombre de rol.

¿Cómo viajan los tokens de rol al código y a las herramientas de diseño?

Los nombres de rol son el contrato; los formatos son transportes. Desde una única fuente DTCG, el mismo conjunto se exporta como propiedades personalizadas de CSS, como un bloque @theme de Tailwind v4 y como Variables de Figma — de modo que el body-md que un diseñador aplica en Figma y el body-md que un desarrollador referencia en una hoja de estilos son el mismo token, no dos convenciones que casualmente riman. Ese vocabulario compartido es la verdadera recompensa de nombrar por rol: «ponlo en heading-sm» es una instrucción que ambas partes pueden ejecutar sin una tabla de traducción, y un reajuste de escala se propaga a cada superficie regenerando las exportaciones en lugar de renombrar nada.

Nombra tu propio conjunto

Nombrar es más fácil mientras los valores siguen vivos: abre el mismo conjunto de roles como salida @theme de Tailwind v4, renombra un nivel y comprueba el instinto que importa — ¿seguiría siendo cierto este nombre si mañana cambiara cada valor en píxeles del archivo? Si la respuesta es sí, es un rol. Si es no, es un valor con una etiqueta de nombre puesta.