Comparativa

Style Dictionary 3 vs 4: la llegada del soporte DTCG

Style Dictionary 3 Style Dictionary 4

La versión 4 acepta tokens W3C DTCG nativos (`$value`, `$type`, `$extensions`), elimina el modelo CTI implícito, reescribe la API de transforms y rompe varios formatos heredados. La migración merece la pena si el destino del sistema es ser consumido por agentes.

Qué es Style Dictionary

Style Dictionary es la herramienta más usada para compilar design tokens desde un JSON canónico a múltiples formatos de salida: CSS custom properties, Swift, Android XML, JSON aplanado, etc. Amazon liberó la primera versión en 2017. Mantenida ahora por la comunidad bajo la organización amzn/style-dictionary.

La versión 4 se publicó como estable en 2024 e introdujo cambios que rompen retrocompatibilidad con 3.x. La pregunta para un sistema en producción es: ¿cuánto cuesta migrar y qué se gana?

Cambios entre versiones

1. Soporte DTCG nativo

Style Dictionary 3 usa un formato propio:

{
  "color": {
    "ink": {
      "graphite": {
        "value": "#0E0E0E",
        "comment": "Tinta principal"
      }
    }
  }
}

El tipo se infería por la posición del nodo en el árbol (modelo CTI: Category-Type-Item). color.ink.graphite se inferia como tipo color porque el padre se llamaba color. Frágil y propietario.

Style Dictionary 4 acepta tokens DTCG directos:

{
  "color": {
    "ink": {
      "graphite": {
        "$value": "#0E0E0E",
        "$type": "color",
        "$description": "Tinta principal"
      }
    }
  }
}

Tipo explícito. Sin inferencia. Sin modelo CTI implícito. El JSON es portable entre herramientas (Style Dictionary, Tokens Studio, Theo, custom build pipelines).

2. API de transforms reescrita

En 3.x los transforms recibían prop (la propiedad). En 4.x reciben token y exponen el contexto DTCG completo, incluyendo $extensions.

// SD 4.x
StyleDictionary.registerTransform({
  name: "size/px",
  type: "value",
  filter: (token) => token.$type === "dimension",
  transform: (token) => `${token.$value}px`,
});

El cambio significa reescribir cada transform custom del sistema. Si tenías diez, son diez ediciones. La lógica de negocio rara vez cambia; sólo el shape de la función.

3. Formatos eliminados

Los formats heredados (scss/variables-with-deprecation, varios formatos Android específicos) están eliminados o requieren plugin. Para un sistema que sigue usando Sass como output principal, esto es un blocker hasta verificar el patch path.

4. Async first

Toda la API de Style Dictionary 4 es async. Los hooks (registerTransform, registerFormat, etc.) aceptan funciones async. Esto es necesario para integraciones que leen de remote (un MCP server, una API de Figma) pero rompe la firma del build pipeline.

Path de migración

Para un sistema con menos de 200 tokens y menos de 5 transforms custom, la migración cabe en una sesión:

  1. Renombrar value → $value, comment → $description (regex global).
  2. Añadir $type a cada nodo terminal. Si el tipo era inferido por CTI, derivarlo del nombre del padre.
  3. Trasladar metadata custom a $extensions.<namespace>. Por convención <empresa>.<área>, ejemplo: $extensions.ida.agentic.
  4. Reescribir cada registerTransform para usar la nueva firma con token en vez de prop.
  5. Reescribir cada registerFormat async, verificar que las salidas siguen siendo idénticas byte-a-byte.
  6. Eliminar el modelo CTI del config ({ tokens: { color: { ink: ... } } } → tokens.json plano).

Para sistemas más grandes, vale la pena escribir un script de migración tipo migrate-sd3-to-sd4.mjs que aplique los pasos 1-3 sobre el árbol completo. Los pasos 4-5 son inherentemente manuales: dependen de la lógica concreta de cada transform.

Cuándo no migrar todavía

Tres situaciones donde mantener Style Dictionary 3 es razonable:

  1. Tu sistema no está pensado para consumo agéntico. Si el único consumidor es el producto web propio y no hay plan a 12 meses de exponer un MCP server, el JSON propietario funciona y la migración no compensa.

  2. Plugins críticos sin paridad en 4.x. Algunos plugins comunitarios (Figma Tokens Sync, Tokens Studio for Sketch) tienen versiones para 3.x más maduras. Verificar el ecosistema concreto antes de mover.

  3. Sistema en mantenimiento, no en evolución. Si el sistema está en modo “se le hace deprecation, no nuevo desarrollo”, migrar añade ruido sin retorno. Mejor congelar 3.x y planificar la próxima generación directamente en 4.x.

En los demás casos (cualquier sistema con horizonte agéntico), la migración a 4.x se debe a una sola razón: el JSON DTCG es lo que cualquier agente entiende sin reentrenamiento. Sin esa portabilidad, el sistema queda atrapado en su herramienta.

Ver también

La mini-formación de tokens W3C DTCG incluye el script de migración SD3→SD4 listo para usar. Para un acompañamiento completo del cambio, el bootcamp ejecutivo cubre el patrón en la semana 04.

Ver todas las comparativas