Nombrar
Dos escuelas
Dos formas de nombrar los tokens semánticos, propiedad primero y pares de rol, con ejemplos del SDS de Figma, Atlassian y shadcn/ui, y por qué DesignToken101 elige la primera.
Última revisión:
En esta lección comparas dos formas de nombrar los tokens semánticos, cada una con ejemplos de sistemas de diseño publicados. Una pone la propiedad al principio del nombre; la otra nombra un rol y le añade una pareja para lo que va encima. Al final verás por qué DesignToken101 eligió la primera.
En esta página
- Propiedad primero
- Pares de rol
- Las dos escuelas frente a frente
- Por qué DesignToken101 pone la propiedad primero
- Los pares on
- Lo que te llevas
Propiedad primero
En esta escuela, el nombre dice primero a qué se aplica el token: fondo, texto o borde. Después vienen el rol y el resto de niveles.
El Simple Design System (SDS) de Figma nombra así sus tokens de color. Algunos ejemplos de su archivo de tokens (SDS: theme.css):
| Token del SDS | Propiedad | Rol | Resto |
|---|---|---|---|
--sds-color-background-brand-default | background | brand | default |
--sds-color-text-danger-default | text | danger | default |
--sds-color-border-neutral-secondary | border | neutral | secondary |
Atlassian describe la misma estructura en su documentación: primero la base (color, space), después la propiedad (background, text, border) y al final los modificadores, como el rol, el énfasis o el estado. Uno de sus ejemplos es color.icon.success (Atlassian: Design tokens).
El curso de Figma sobre sistemas de diseño da el mismo consejo de forma general: que los prefijos sean coherentes, y que los tokens de fondo empiecen todos por background en vez de tenerlo en otra parte del nombre (Figma: Update 1, Tokens, variables, and styles).
Pares de rol
En esta escuela, el nombre dice primero el rol, y la propiedad se deduce de una convención de parejas.
shadcn/ui nombra así sus variables. Su documentación explica que usa pares de fondo y primer plano: el token base controla el color de la superficie y el token con -foreground controla el texto y los iconos que van encima (shadcn/ui: Theming):
| Token base (superficie) | Token -foreground (lo que va encima) |
|---|---|
--background | --foreground |
--primary | --primary-foreground |
--muted | --muted-foreground |
--card | --card-foreground |
Algunos tokens no tienen pareja, como --border o --ring. En Tailwind CSS, los pares dan clases cortas: bg-primary text-primary-foreground.
Las dos escuelas frente a frente
| Propiedad primero | Pares de rol | |
|---|---|---|
| Ejemplo de texto principal | color/text/neutral/default | --foreground |
| Ejemplo de botón principal | color/background/accent/strong/default | --primary |
| Qué dice el nombre | A qué se aplica, qué rol tiene y con cuánto énfasis | El rol; la propiedad sale de la pareja |
| Longitud | Nombres largos | Nombres cortos |
| En Figma | Cada propiedad puede tener su scope | La propiedad no está en el nombre |
| Clases de Tailwind CSS | Redundantes si se exponen tal cual (text-text-…) | Cortas (bg-primary) |
| Quién la usa | SDS de Figma, Atlassian | shadcn/ui |
Ninguna de las dos es "la correcta". Son dos equilibrios distintos entre lo explícito y lo breve.
Por qué DesignToken101 pone la propiedad primero
Recomendación
DesignToken101 usa propiedad primero, como el SDS de Figma y Atlassian. Es una decisión nuestra, por tres motivos:
- El nombre y el scope dicen lo mismo. En Figma, el scope limita las propiedades en las que se ofrece una variable (Figma: Create and manage variables). Todos los
color/text/*llevan el scope de texto, todos loscolor/background/*el de relleno. Al elegir el color de un texto, ves únicamente tokens de texto. Lo viste en Un scope por propiedad. - El contraste se comprueba por pares legibles.
text/neutral/defaultsobrebackground/neutral/defaultse lee en el propio nombre. - El público principal son diseñadores, que trabajan en Figma. La ventaja del scope se nota en Figma; la desventaja, en el código.
El coste está en Tailwind CSS: con nombres de propiedad primero, una clase de color de texto repetiría la palabra (text-text-neutral-default). DesignToken101 lo resuelve en código, sin cambiar los nombres de Figma. Cómo lo verás en el módulo De Figma al código; tienes un adelanto en Cómo encajan Figma, DTCG y Tailwind.
Los pares on
Hay un caso en el que la escuela de pares acierta: el texto que va sobre un fondo de color fuerte. El texto del botón principal no es un texto cualquiera; depende del fondo del botón. Si cambia uno, hay que revisar el otro.
DesignToken101 toma esa idea y la escribe con su propia estructura: un texto sobre un fondo de rol se llama on-{rol} (regla 7 de la convención).
| Fondo | Texto que va encima |
|---|---|
color/background/accent/strong/default | color/text/on-accent |
El SDS de Figma hace algo parecido, con el on- dentro del rol: --sds-color-text-brand-on-brand, --sds-color-text-danger-on-danger (SDS: theme.css). Cada par on- se comprueba con WCAG 2.2: el de DesignToken101 da 9,63:1 en Light y en Dark.
Lo que te llevas
- Propiedad primero dice a qué se aplica el token; los pares de rol dicen el rol y deducen la propiedad de la pareja.
- DesignToken101 pone la propiedad primero porque encaja con los scopes de Figma, y lo paga con clases redundantes en Tailwind CSS.
- De la escuela de pares toma los tokens
on-, para el texto sobre un fondo de color fuerte.