Style Dictionary vs exportación directa

Dos configuraciones de tokens, una al lado de la otra. La primera es un repositorio con un directorio build/: una configuración de Style Dictionary, una lista de transformaciones personalizadas, una dependencia de npm con sus propias notas de versión y destinos de salida para web, iOS, Android y un sitio de documentación. La segunda es un generador cuyo panel de exportación escribe CSS, un tema de Tailwind y Figma Variables directamente, con el archivo de tokens versionado junto al código y sin ningún paso de compilación. Ningún equipo lo está haciendo mal: tienen problemas con formas distintas.

Style Dictionary es un pipeline de transformación: toma un archivo fuente de tokens y lo hace pasar por transformaciones y formatos configurables para emitir cualquier destino que definas. La exportación directa es la propia herramienta generadora emitiendo los formatos comunes, sin pipeline que configurar. El pipeline es el camino correcto cuando tienes muchos destinos o destinos a medida; la exportación directa es el camino correcto cuando los destinos web estándar te cubren, y como un archivo DTCG canónico puede alimentar un pipeline más adelante, elegir la exportación directa hoy no te cierra la puerta al pipeline mañana.

Este es el capítulo sobre herramientas de nuestra guía de design tokens: qué es realmente cada camino, una comparación honesta y el mismo token seguido por ambos.

¿Qué es Style Dictionary?

La herramienta de código abierto que define la categoría de la transformación de tokens, documentada en styledictionary.com: cuando surgen los pipelines de compilación de tokens, suele ser el punto de referencia, y es infraestructura complementaria más que un competidor de cualquier generador. No es una herramienta de diseño: no tiene ninguna opinión sobre cuáles deberían ser tus valores ni interfaz para decidirlos. Consume una fuente de tokens, hace pasar cada token por transformaciones —renombrar a la convención de mayúsculas de una plataforma, convertir unidades, reformatear colores para la sintaxis del destino— y entrega los resultados a formatos que escriben los archivos de destino: propiedades personalizadas de CSS, mapas de Sass, constantes de Swift, XML de recursos de Android, JSON para un sitio de documentación. Cada articulación es configurable, y las transformaciones personalizadas son código corriente que escribes y del que eres dueño.

Esa forma deja claro su terreno natural: muchos destinos, reglas de nomenclatura específicas por plataforma, un pipeline de compilación existente en el que encajar. Se ejecuta como un paso de compilación, y los equipos de plataforma lo tratan como tal.

¿Qué es la exportación directa?

La herramienta que generó el sistema también escribe los formatos de consumo. Scale Composer funciona así: deriva la tipografía, el espaciado, las rampas de color y los roles semánticos claro/oscuro a partir de una única escala compartida, y luego exporta un archivo de tokens DTCG canónico junto con propiedades personalizadas de CSS, un bloque @theme de Tailwind v4 y Figma Variables, con el hex acompañando al OKLCH: sin configuración, sin dependencia de compilación, nada que mantener salvo la propia salida.

El límite honesto es el menú: la exportación directa cubre los formatos que cubre. Para la mayoría de los productos web —una hoja de estilos, un tema de utilidades, un archivo de diseño— el menú es la comida completa. Pero un destino que no está en el menú no se puede añadir mediante configuración, porque no hay configuración; ahí es precisamente donde empieza el territorio del pipeline.

¿Cómo se comparan los dos caminos?

La tabla es honesta en ambas direcciones. «Cualquier destino» es un poder real que cuesta una propiedad real: la configuración, las transformaciones y las actualizaciones de dependencias pertenecen a alguien de tu equipo. «Sin configuración» es un ahorro real que compra un menú fijo. Ninguna columna domina; la fila decisiva suele ser la última.

Abre las exportaciones directas una al lado de la otra en Scale Composer — un sistema generado renderizado simultáneamente como archivo DTCG, propiedades personalizadas de CSS, un tema de Tailwind y Figma Variables.

¿Tienes que elegir?

A menudo, no, y este es el punto central del artículo: como la salida canónica de Scale Composer es DTCG estándar, el archivo que produce la exportación directa es una fuente válida para un pipeline de transformación. Usa la exportación directa para el bucle cotidiano: decidir, exportar, versionar, consumir. El día que una app nativa aparezca en la hoja de ruta, apunta la fuente de Style Dictionary a ese mismo archivo versionado y añade los nuevos destinos; no se reescribe nada y el bucle cotidiano no cambia. El formato de intercambio es lo que hace que los dos caminos sean componibles en lugar de excluyentes: la recompensa de estandarizar sobre DTCG en lugar de sobre el dialecto privado de cualquier herramienta.

El bloqueo tecnológico falla en ambas direcciones. Abandona el generador y el archivo DTCG sigue siendo una entrada válida para el pipeline. Adopta el generador tarde e importará un archivo DTCG existente, preservando las secciones que no genera a través del viaje de ida y vuelta.

¿Cuándo se te ha quedado pequeña la exportación directa por sí sola?

Tres señales, cualquiera de las cuales es suficiente:

1. Un destino que los formatos integrados no cubren. Recursos de apps nativas, variables de plantillas de correo, un sitio de documentación tematizado: cualquier cosa que necesite una forma de archivo que el menú de exportación no ofrezca.
2. Transformaciones de nomenclatura por plataforma. La web quiere --color-accent, Android quiere color_accent, iOS quiere colorAccent: el renombrado sistemático por destino es la tarea que define al pipeline.
3. Generación de documentación. Cuando el archivo de tokens también debe producir páginas de referencia, la documentación no es más que otro destino de formato.

Fíjate en la forma del movimiento cuando llega una señal: adición, no migración. El pipeline consume el archivo que el bucle cotidiano ya produce.

¿Qué aspecto tiene el mismo token por cada camino?

Toma una decisión semántica: accent referencia a brand-600, que almacena #2563eb, oklch(0.546 0.215 262.9).

Camino directo. La exportación de CSS escribe la propiedad personalizada resuelta:

:root {
  --accent: #2563eb; /* semantic.accent → color.brand.600 */
}

Camino del pipeline. Una configuración —esbozada aquí por su forma; la API exacta vive en la documentación de la herramienta— apunta al mismo archivo canónico y pide un destino de tipo Android:

// configuración de style-dictionary, forma no literal
{
  source: ["design-tokens.json"],   // exportación canónica de Scale Composer
  platforms: {
    android: {
      transforms: ["name → snake_case", "color → #AARRGGBB"],
      files: [{ format: "android/resources", destination: "colors.xml" }]
    }
  }
}

emitiendo un recurso de la clase colors.xml:

<color name="semantic_accent">#FF2563EB</color>

La misma decisión, dos renderizados: los puntos se convirtieron en guiones y una propiedad personalizada por un camino, snake_case y hex con el alfa primero por el otro. El valor es idéntico en ambos, porque ambos caminos leen la misma fuente: todo el argumento, visible en tres líneas de salida.

Parte del archivo que comparten ambos caminos

Sea cual sea el camino que encaje hoy, empieza en el mismo artefacto. Exporta el archivo de tokens DTCG canónico desde Scale Composer — las exportaciones directas a su lado para el bucle cotidiano, y el propio archivo listo para ser la fuente de un pipeline el día que aparezca un nuevo destino.