Design Tokens: Cómo los Sistemas de Diseño Reales Mantienen la Consistencia
Qué son los design tokens, el modelo de tres niveles que usan los sistemas reales (Shopify Polaris, IBM Carbon, GitHub Primer), cómo nombrarlos, theming para dark mode, y cuándo los tokens son exagerados.
Design Tokens: Cómo los Sistemas de Diseño Reales Mantienen la Consistencia
Un código hex es un valor. Un token es una decisión con nombre. Los sistemas de diseño están hechos de decisiones, no de valores.
Esa distinción es todo el punto. Hardcodea #0EA5E9 en catorce componentes de Figma, te piden dark mode, y estás frente a una semana de buscar y reemplazar. Nómbralo color-interactive-primary y cambias un valor mientras cada superficie se actualiza. Eso no es magia, solo decisiones con nombre.
Qué es realmente un design token
Un design token es una variable con nombre que almacena una decisión de diseño. Puede guardar un color, un valor de espaciado, un tamaño de fuente, un radio de borde, una sombra, una duración. El nombre es el contrato. El valor detrás del nombre puede cambiar sin romper nada que use el token.
El enfoque clásico sin tokens empieza cuando un diseñador elige #1D4ED8 para los botones primarios, lo hardcodea en el componente de botón, luego copia ese hex en la tarjeta, el badge y el enlace. Seis meses después, la marca se actualiza. Ahora tienes un problema de mantenimiento que escala con cada componente que enviaste.
Los tokens dan vuelta eso. Nombras la decisión (color-action-default), asignas el valor una vez, y todo lo que referencia el token se mantiene sincronizado. El valor es un detalle de implementación. El nombre es el sistema.
Los tres niveles que hacen funcionar a los tokens
Los tokens sin procesar son solo variables. Lo que hace que un sistema de tokens sea realmente útil es la jerarquía. Cada sistema de producción que vale la pena estudiar usa tres niveles.
| Nivel | También Llamado | Qué Almacena | Ejemplo |
|---|---|---|---|
| Primitivo | Global, Base | Valores crudos, sin significado | color.blue.500 = #3B82F6 |
| Semántico | Alias, Rol | Roles con nombre mapeados a primitivos | color.interactive.default = color.blue.500 |
| Componente | Específico | Decisiones con alcance de componente | button.background.default = color.interactive.default |
Los primitivos son tu paleta. Cada azul, cada paso de espaciado y cada radio vive aquí como un valor con nombre sin opinión sobre dónde se usa. No consumes primitivos en componentes directamente.
Los tokens semánticos mapean roles a primitivos. El token color-surface-default puede apuntar a casi blanco en light mode y casi negro en dark mode, y el componente nunca sabe qué valor crudo recibe. Solo conoce el rol.
Los tokens de componente son los más específicos. Existen cuando un componente necesita una decisión que es intencionalmente diferente al valor semántico por defecto. Un botón de peligro apunta su fondo a un rol de feedback crítico en lugar del interactivo por defecto. La mayoría de los componentes no necesitan sus propios tokens; consumen los semánticos directamente.
Por qué los tokens superan a los valores hardcodeados
La velocidad de cambio es el argumento obvio, pero no es el real. El argumento real es la precisión.
Cuando un diseñador entrega un archivo lleno de códigos hex crudos, el desarrollador no tiene idea de cuáles son intencionales y cuáles son accidentales. ¿Es #1A1A2E el fondo, o alguien usó el cuentagotas en la capa equivocada? Los tokens eliminan la ambigüedad. Un nombre de token semántico es documentación que viaja con el valor.
Los tokens también son el contrato de handoff entre herramientas de diseño y código en 2026. Las variables de Figma se mapean directamente a propiedades personalizadas de CSS. Un token definido en un archivo de Figma puede exportarse, commitearse y consumirse en código sin un solo paso manual. La brecha entre diseño e implementación se colapsa cuando ambos lados hablan los mismos nombres de token.
Para equipos haciendo trabajo de accesibilidad, los tokens añaden otra capa de seguridad. Auditas la paleta semántica en un solo lugar y garantizas que color-text-default siempre supera el contraste 4.5:1 contra color-surface-default, sin importar qué tema esté activo.
Cómo los sistemas de diseño reales estructuran sus tokens
Tres sistemas vale la pena conocer: Shopify Polaris, IBM Carbon y GitHub Primer. Manejan el modelo de tres niveles de forma diferente, y las diferencias son instructivas.
Shopify Polaris mantiene los primitivos en una escala de colores (color-sky-100 hasta color-sky-900) y los aliasa a roles semánticos como --p-color-bg-fill-active. Los tokens de componente son escasos, así que la mayoría de los componentes consumen tokens semánticos. La convención es rol-luego-estado, que se lee naturalmente en código, ya que sabes para qué es bg-fill-disabled sin contexto adicional.
Ver en vivo en polaris.shopify.com
IBM Carbon va profundo en las capas semánticas. Su conjunto de colores incluye tokens de feedback explícitos como support-error y support-success, tokens de estado interactivo y tokens de capa para superficies anidadas (un componente en un panel en una página necesitan cada uno un valor de superficie diferente). Es más complejo, pero IBM hace software empresarial donde cada estado anidado importa.
Ver en vivo en carbondesignsystem.com
GitHub Primer expone su capa primitiva como "primitives" y su capa semántica como "functional tokens", documentados públicamente en primer.style. El theming de Primer le permite a GitHub publicar light, dark, light high contrast y dark dimmed desde un solo conjunto de componentes. Cada tema es una asignación de valores diferente para los mismos nombres de token.
El patrón en los tres es consistente: primitivos como escala, tokens semánticos como nombres de rol, y theming como un intercambio de valores en la capa semántica. Los componentes se mantienen sin cambios.
Brainy ayuda a los diseñadores a construir sistemas que escalan, no pantallas únicas. Mira qué estamos construyendo para creadores en /creators.
Nombrar tokens sin perder la cabeza
El nombrado de tokens rompe equipos. Demasiado genérico y los nombres no llevan información. Demasiado específico y escribes un nuevo token para cada componente.
Una convención de nombrado que funciona nombra cuatro partes: categoría, rol, variante y estado. No usarás las cuatro cada vez, pero la estructura previene el caos ad-hoc.
| Parte | Qué Captura | Ejemplos |
|---|---|---|
| Categoría | La propiedad de diseño | color, spacing, radius, shadow, font |
| Rol | El propósito semántico | surface, text, border, interactive, feedback |
| Variante | Sub-rol o modificador | primary, secondary, danger, subtle |
| Estado | Condición interactiva | default, hover, active, disabled, focus |
Ejemplos de trabajo, escritos como las propiedades personalizadas CSS que un desarrollador realmente consume:
color-surface-defaultestablece el fondo de página por defectocolor-text-subtlees texto secundario con menor contrastecolor-interactive-primary-hoveres el estado hover de una acción primariaspacing-component-mdes el padding interno medio para componentesradius-interactivees el radio de esquina para elementos clicables
Dos reglas salvan la mayoría de los debates. Nunca codifiques el valor crudo en el nombre, porque color-blue-500 no dice nada sobre el rol. Nunca nombres por componente en la capa semántica, porque button-primary-color en el nivel semántico significa que saltaste la capa semántica por completo.
Para sistemas de tipo que escalan, aplica la misma convención, y font-size-body-lg supera a text-18px siempre.
Un conjunto de tokens, light y dark mode
El dark mode es donde los sistemas de tokens pagan más visiblemente. Si nombraste tus tokens por rol, el dark mode es un intercambio de valores, no un rediseño.
El mecanismo es directo. Tu token semántico color-surface-default apunta a un primitivo que es casi blanco en light mode y casi negro en dark mode. El componente que lo consume nunca cambia. Cambias temas intercambiando el mapeo de valores en la capa semántica.
Las propiedades personalizadas CSS hacen esto mecánico:
:root {
--color-surface-default: #ffffff;
--color-text-primary: #111827;
}
[data-theme="dark"] {
--color-surface-default: #0f172a;
--color-text-primary: #f8fafc;
}
Cada componente que referencia var(--color-surface-default) ahora responde al atributo de tema sin código adicional. Shopify Polaris, GitHub Primer e IBM Carbon todos usan este patrón a escala de producción.
El modo de falla es mezclar tokens semánticos y primitivos en componentes. Cuando un componente referencia color-blue-600 directamente en lugar de color-interactive-primary, ese componente deja de responder al theming. Una sola referencia primitiva descuidada rompe todo el modelo. Las reglas de lint que marcan el consumo directo de primitivos en código de componentes valen el tiempo de configuración.
Entender cómo aterrizan las elecciones de color te da el fundamento conceptual, y los tokens te dan la estructura para actuar sobre ello en cada tema.
Cuándo los design tokens son exagerados
Los tokens añaden indirección. La indirección tiene costos. Sé honesto sobre cuándo esos costos vale la pena pagar.
| Situación | ¿Tokens? | Razón |
|---|---|---|
| Sistema de diseño para 3+ productos | Sí | Los tokens compartidos se pagan solos al instante |
| Producto único, 5+ diseñadores | Sí | Previene la deriva de paleta en el equipo |
| Producto único, 1-2 diseñadores, iteración activa | Quizás | Solo capa semántica, omite tokens de componente |
| Sitio de marketing, sin biblioteca de componentes | No | Una sola hoja de estilos es más rápida de cambiar |
| Prototipo o MVP menor a 3 meses | No | Abstrae después de que el diseño se estabilice |
| Añadir dark mode a un sistema existente | Sí | Exactamente para eso son los tokens |
Los equipos pequeños se mueven más rápido sin tokens. Una startup de tres personas persiguiendo product-market fit no necesita una jerarquía de tres niveles. Cuando cambias la dirección visual cada dos semanas, una única biblioteca de estilos de Figma es suficiente.
El anti-patrón a evitar es el nombrado semántico prematuro. Tokens llamados color-blue y color-gray añaden indirección sin significado. O nombras por rol con color-surface y color-text, o te quedas con primitivos hasta que tengas suficientes componentes para saber cuáles son realmente los roles.
El mal nombrado de tokens es peor que no tener tokens. Un token llamado button-color-for-the-checkout-page en la capa semántica es una trampa de mantenimiento. La disciplina de nombrado no es opcional, es la razón por la que los tokens funcionan en absoluto.
FAQ
¿Los design tokens reemplazan los estilos de Figma?
No, pero los extienden. Las variables de Figma, lanzadas en 2023, son el equivalente nativo más cercano dentro de Figma, y se mapean a tokens de código cuando compartes convenciones de nombrado entre ambos. Los estilos de Figma manejan tipografía y rellenos de color, mientras que las variables manejan la jerarquía completa de tokens incluyendo estados y decisiones a nivel de componente.
¿Funcionan los tokens sin un sistema de diseño?
Los tokens son más valiosos dentro de un sistema de diseño, pero incluso un solo producto se beneficia del nombrado semántico a nivel de propiedad personalizada CSS. No necesitas un sistema formal para dejar de hardcodear valores hex.
¿Qué herramienta debería usar para gestionar tokens?
Para equipos pequeños, las variables de Figma más una exportación JSON son suficientes. Para equipos más grandes, Style Dictionary (open source, de Amazon) es la herramienta de build estándar. Toma una estructura JSON de tokens y produce propiedades personalizadas CSS, constantes Swift para iOS y XML para Android. Tokens Studio para Figma es el plugin puente popular entre Figma y Style Dictionary.
¿Qué tan granulares deben ser los tokens de componente?
Solo tan granulares como necesites. La mayoría de los componentes pueden consumir tokens semánticos directamente. Los tokens específicos de componente tienen sentido cuando un componente diverge de la capa semántica a propósito, como un botón de acción destructiva o un banner con una superficie inusual. En caso de duda, consume semántico y crea tokens de componente solo cuando te encuentres escribiendo excepciones.
¿Pueden los tokens manejar espaciado y tipografía, o solo color?
Los tokens funcionan para cualquier cosa con un valor discreto: color, espaciado, tipografía, radio de borde, sombra de caja, duración de movimiento, easing de movimiento y z-index. Los sistemas más maduros, como IBM Carbon y Atlassian Design System, tienen tokens para todo esto. Empieza con color y espaciado, luego agrega otros a medida que el sistema madura.
Deja de hardcodear valores
El camino práctico no es complicado:
- Nombra tus primitivos como una escala
- Mapea esos primitivos a roles semánticos
- Haz que cada componente consuma tokens semánticos, nunca primitivos
- Exporta los valores de tokens desde una sola fuente (variables de Figma, un archivo JSON o un paquete de sistema de diseño) y deja que las herramientas de build los distribuyan a CSS, iOS y Android
No necesitas una migración de tres meses para empezar. Elige un componente, nombra sus decisiones, y siente la diferencia cuando cambias un valor una vez y ves cómo todo se actualiza. Esa experiencia es el argumento.
Para más escritura sobre sistemas de diseño, mira qué más cubre Brainy en /paper.
Brainy helps designers build systems that scale, not one-off screens. See what we are building for creators.
Get Started
