Documentación técnica
Cómo se generan los tokens en Tokenalia
Esta página describe la lógica de generación de tokens orientada a diseño de producto. El objetivo es que el sistema resultante sea consistente, perceptualmente uniforme y verificable en accesibilidad.
1) Flujo general de generación
Tokenalia trabaja en dos modos:
- Modo rápido: con entradas mínimas (marca, color primario, gris base y tipografía) se derivan rampas y valores por defecto.
- Modo customizado: permite ajustar explícitamente decisiones por categoría (color, typo, spacing, grid, motion).
Internamente, el proceso se divide en tres fases:
- Normalización: limpieza y validación de entradas (hex, tamaños, unidades, etc.).
- Derivación: cálculo de escalas (rampas tonales, size steps, espaciado progresivo).
- Empaquetado: salida en formato de Design Tokens Community Group (W3C draft) en JSON.
2) Rampa de color + validaciones WCAG y APCA
Las escalas cromáticas se calculan en espacio perceptual OKLCH, lo que reduce saltos visuales entre pasos. A partir de un color semilla, se ajustan lightness y chroma por niveles para construir la rampa (ej. 50-900).
Validaciones de contraste
- WCAG 2.x (AA/AAA): se valida ratio de contraste entre pares foreground/background (por ejemplo, texto principal sobre superficie).
- APCA: se evalúa el contraste perceptual para lectura real en UI moderna, complementando la métrica WCAG.
- Recomendación: usar ambas métricas: WCAG para cumplimiento normativo y APCA para calidad visual percibida.
En el showcase se presentan estos pares con feedback para detectar combinaciones que no alcancen umbrales objetivo.
color.primary.500 -> base del sistema color.primary.700 -> texto/acento sobre fondos claros color.neutral.100..900 -> superficies y jerarquía de UI3) Escala tipográfica
La tipografía se genera desde una base (ej. 16px) y un ratio (ej. 1.2, 1.25 o 1.333). Con ello se crean niveles semánticos para display, headings, body y captions.
- Size tokens: pasos de tamaño coherentes para componentes y layout.
- Line-height tokens: valores que priorizan legibilidad y ritmo vertical.
- Weight tokens: pesos disponibles de la familia tipográfica elegida.
El objetivo no es solo "más grande/más pequeño", sino mantener proporciones consistentes entre bloques textuales.
4) Escala de espaciado
La escala de spacing parte de una unidad base (ej. 4px o 8px) y genera valores secuenciales para márgenes, paddings y separaciones.
- Micro-espacios: densidad de componentes (2, 4, 8).
- Espacios estructurales: separación de bloques y secciones (16, 24, 32, 40, 48...).
- Uso recomendado: limitarse a la escala para reducir decisiones ad-hoc y deuda visual.
5) Otros tokens derivados
- Grid: columnas, gutters y max-width para composición responsive.
- Border: radios y grosores para consistencia de superficies y componentes.
- Elevation: sombras por nivel para jerarquía espacial.
- Motion: duraciones y curvas de easing para transiciones y feedback.
- Focus: estilos de enfoque para navegación por teclado y accesibilidad.
6) Formato de salida
El archivo final `tokens.json` sigue la estructura de Design Tokens W3C (draft), de forma que pueda mapearse después a CSS variables, librerías de componentes o pipelines de build (por ejemplo, transformación a plataformas web/mobile).
{ "color": { "primary": { "500": { "$value": "#5B4BF5" } } }, "typography": { "body-md": { "$value": { "fontSize": "16px", "lineHeight": "24px" } } }, "spacing": { "4": { "$value": "16px" } } }Si quieres, el siguiente paso puede ser enlazar esta documentación también desde el showcase para que quede disponible en ambos puntos del producto.