Style Dictionary: transformación y generación de tokens

Style Dictionary (creado por Amazon) es una herramienta de compilación que toma definiciones de tokens en formato JSON y las genera en cualquier formato de destino: propiedades personalizadas de CSS, módulos ES de JavaScript, variables de Sass, constantes de Swift para iOS, recursos XML para Android y cualquier formato personalizado que se defina. Una única fuente de verdad, múltiples salidas.

Instálelo con npm install --save-dev style-dictionary. Inicialice la estructura del proyecto con npx style-dictionary init; esto crea un config.json (o config.js) y un directorio tokens/. La configuración indica a Style Dictionary dónde encontrar los archivos de tokens y dónde escribir las salidas.

Style Dictionary utiliza una estructura JSON anidada cuyos nodos hoja tienen una propiedad value. Por ejemplo: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. La ruta hasta el valor (color, primary, 500) se convierte en el nombre del token después de la transformación, normalmente con el formato color-primary-500 o --color-primary-500.

Ejecute npx style-dictionary build --config config.json (o style-dictionary build si está configurado en los scripts de package.json). Style Dictionary lee todos los archivos de tokens del origen configurado, aplica las transformaciones y escribe las salidas en los destinos configurados. Los errores en el formato de los tokens se notifican junto con el nombre y la ruta del archivo.

El archivo config.json define plataformas: css (genera un archivo CSS con propiedades personalizadas), js (genera un objeto JS) y scss (genera variables de Sass). Cada plataforma especifica el directorio de salida, el nombre del archivo, el formato (la plantilla) y las transformaciones (las funciones que procesan el nombre y el valor) que se deben aplicar.

Style Dictionary incluye transformaciones integradas: name/cti/kebab convierte la ruta anidada en color-primary-500, name/cti/camel genera colorPrimary500, size/rem convierte valores en píxeles a rem y color/hex normaliza los colores al formato hexadecimal. Las transformaciones se pueden combinar y se aplican en orden.

Puede registrar transformaciones personalizadas con StyleDictionary.registerTransform(). Por ejemplo, una transformación que convierta valores en píxeles a puntos de iOS o que añada un prefijo específico de la empresa a todos los nombres de tokens. Las transformaciones personalizadas le proporcionan control total sobre el procesamiento de los valores antes de generar la salida.

Los formatos personalizados definen la plantilla del archivo de salida. StyleDictionary.registerFormat() recibe el diccionario de tokens transformados y devuelve una cadena: el contenido del archivo. Puede generar los tokens como tipos de TypeScript, como un objeto de tema de React, como una extensión de configuración de Tailwind o en cualquier otro formato que requiera su stack.

Después de compilar, importe la salida CSS en la hoja de estilos global: @import './tokens/tokens.css'. Importe la salida JS en los componentes o en la configuración de Tailwind: import tokens from './tokens/tokens.js'. CSS le proporciona propiedades personalizadas para aplicar temas en tiempo de ejecución; JS le proporciona constantes tipadas para Tailwind y la lógica de JavaScript.

Style Dictionary admite referencias a tokens mediante llaves: { "value": "{color.primary.500}" }. Esto crea alias de tokens semánticos: el token semántico hace referencia a un token primitivo. Durante la compilación, Style Dictionary resuelve las referencias y genera el valor final resuelto (o una referencia a una variable CSS, según el formato).

Ejecute Style Dictionary como un script npm prebuild para que los tokens siempre se regeneren antes de compilar la aplicación. Añada "prebuild": "style-dictionary build" a package.json. Así se garantiza que cualquier cambio en los archivos JSON de tokens se refleje en las salidas CSS y JS antes de que la compilación de React las procese.

¿Cuál es el propósito de las transformaciones en Style Dictionary?

Style Dictionary convierte el JSON de tokens en cualquier formato de salida: variables CSS, módulos JS, Sass, iOS y Android. El JSON de tokens utiliza objetos anidados con nodos hoja value. Las transformaciones procesan nombres y valores (camelCase, de px a rem); los formatos definen la plantilla de salida. Las referencias a tokens ({color.primary.500}) permiten crear alias semánticos. Automatice el proceso con un script prebuild para que los tokens estén siempre actualizados antes de la compilación de React.