Guía rápida para empezar con Style Dictionary

Creando un proyecto con style dictionary desde cero

Hemos estado viendo como podemos personalizar esta herramienta para generar distribuidles para nuestros tokens en diferentes plataformas y como podemos extender la configuración inicial para hacer literalmente lo que queramos.

Además, en este artículo construimos nuestro propio style-dictionary básico para generar tokens.

Hoy vamos a ver como empezaríamos a usar style dictionary desde 0, suponiendo que tengamos ya nuestros tokens en ficheros JSON. Encima, vamos a ser major y dejaremos al final del artículo el repositorio con el código del ejemplo, para que puedas descargarlo en tu local y trastear :).

Nuestros tokens

Como bien hemos dicho, partimos de la base que ya tenemos nuestros tokens en formato JSON listos para ser transformador. Estos son los ficheros que tenemos:

• base.json

{
   "color": {
      "base": {
          "primary": { value: "#007bff" },
          "secondary": { value: "#00ff00" }
      }
   }
}

• button.json

{
   "color": {
      "background": {
          "button": {
              "primary": { "value": "{color.base.primary}" },
              "secondary": { "value": "{color.base.secondary}" }
           }
      },
      "text": {
           "primary": { "value": "#ffffff" },
           "secondary": { "value": "#333333" }
      }
   }
}

• font.json

{
   "size": {
      "font": {
          "base": { value: "16px" },
          "medium": { value: "18px" },
          "large": { value: "24px" }
      }
   }
}

El el fichero button.json hemos metido unas referencias a los colores definidos en base.json, para no repetir valores.

Generando el proyecto

Ahora vamos a montar el proyecto en el cual guardaremos nuestros tokens y los transformaremos con style-dictionary.

Para ello vamos a usar NodeJS, concretamente la versión 18+.

Lo mejor es instalarlo a través de un gestor de versiones como nvm o n, pero si no te quieres complicar la vida puedes instalarlo fácil si estas en Windows o Mac desde el instalador oficial. Cercionate de que instalas como mínimo la versión 18.15.

Para el que no lo sepa: NodeJS es un runtime de Javascript que utiliza el motor V8 (el mismo motor que utiliza Chrome) y nos permite ejecutar Javascript fuera de un navegador.

Una vez instalado, podemos utilizar el sistema de paquetes oficial (NPM) para crear un nuevo proyecto.

Si estás en linux o Mac, abre una terminal y ves a la carpeta donde tengas tus proyectos y ejecuta:

mkdir nombre-de-tu-proyecto

Donde para sorpresa de nadie, donde pone “nombre-de-tu-proyecto” hay que sustituirlo por el nombre real que queramos darle. En nuestro caso: ‘sd-example’:

mkdir sd-example

Esto nos creará una carpeta sd-example. Ahora nos metemos dentro:

cd sd-example

Y ejecutamos:

npm init -y

Este comando nos inicializará un proyecto NPM. Que quiere decir que nos creará un fichero package.json con los datos de nuestro proyecto.

Si estás en Windows y no eres un desarrollador, te sugiero que instales WSL. Cuando lo tengas, puedes abrir una terminal WSL y ejecutar los mismo comandos que puse arriba.

Instalando Style Dictionary

Style Dictionary es un paquete que se distribuye con NPM, por lo que en el punto en el que estamos es muy sencillo instalarlo.

Para ello en la carpeta del proyecto (donde está el fichero package.json que hemos generado en el paso anterior) ejecuta:

npm i -D style-dictionary

Ya estamos listos para empezar a usarlo!

Estructura de carpetas

Antes de transformar los tokens, necesitamos meterlos dentro de nuestro proyecto.

Vamos a crear una carpeta llamada tokens en la raíz del proyecto y una carpeta para color y otra para size:

mkdir tokens
mkdir tokens/color
mkdir tokens/size

Seguidamente guardaremos los tokens mostrado arriba dentro de cada carpeta, de tal forma que el resultado sea un árbol así:

tokens/
   color/
      base.json
      button.json
   size/
      font.json

Fichero de configuración

La forma más sencilla de empezar con style dictionary es mediante un fichero de configuración JSON donde le diremos:

• Dónde están nuestros tokens.

• Qué transformadores aplicar.

• Qué ficheros para qué plataformas generar.

• En qué formato generarlos.

Para ello, en la raíz del proyecto ejecuta:

touch config.json

Esto creará un fichero config.json en la raíz del proyecto.

Ahora usa tu editor de texto favorito para abrirlo e introduce en él la siguiente configuración:

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "files": [{ 
        "format": "css/variables", 
        "destination": "dist/main.css"
      }]
    }
  }
}

Con la propiedad “source” le estamos diciendo donde están nuestros tokens.

El valor “tokens/**/*.json” viene a decir que busque en la carpeta tokens y en las carpetas dentro ficheros que tengan la extensión .json.

En platforms definimos las plataformas que vamos a generar. El nombre puede ser cualquier cosa. Nosotros hemos usado el nombre de la tecnología de destino a la que queremos generar nuestros distribuibles (css).

Se pueden tener tantas plataformas como se quiera. Todo el proceso de procesado y transformación de tokens se repetirá para cada plataforma.

Dentro de la plataforma que hemos definido (css) nos encontramos dos propiedades: transformGroup y files.

El transformGroup hace referencia a un conjunto de transformadores previamente definidos. Estos pueden ser los de por defecto que ofrece style-dictionary o personalizados que nos creemos nosotros.

Puedes acceder a toda la lista de grupos de transformación predefinidos aquí.

En nuestro caso, vamos a usar el transformGroup css que aplica todas las transformaciones necesarias para servir ficheros en formato css.

La segunda propiedad es files y hace referencia a los ficheros que queremos generar, así como el formato de los mismos. Al ser en plural, es una lista de objetos con dos propiedades: format y destination. El format le dice a style-dictionary el formato en el que debe de escribir el fichero (en nuestro caso como queremos generar un fichero .css con variables css, vamos a usar el formato css/variables).

Finalmente, la propiedad destination es el path y el nombre del fichero de destino a generar. En nuestro caso hemos dicho que se genere una carpeta “dist” y dentro un fichero llamado “main.css” que será el fichero resultante del proceso de transformación y formato.

Al igual que pasaba con los transform groups, puedes encontrar la lista de los formatos previamente definidos aquí.

Generando distribuibles

Ya estamos listos para ejecutar style-dictionary sobre nuestros tokens y generar el fichero que vamos a distribuir.

Para facilitarlos la tarea de lanzar el proceso de style-dictionary, vamos a agregar una entrada de “build” en el apartado “scripts” de nuestro package.json:

 "build": "style-dictionary build"

Si has creado el proyecto siguiendo esta guía, te encontrarás que ya hay un script definido en “scripts” llamado “test”. Puedes dejarlo y poner al final una coma y meter en una nueva línea el código de arriba o puedes borrarlo de tal forma que solo quede el “build”.

Ahora si, podemos ejecutar:

npm run build

Y si todo va bien, deberíamos de ver un mensaje en la consola que diga algo así:

> style-dictionary build


css
✔︎ dist/main.css

Eso quiere decir que nuestro main.css se ha generado correctamente en la carpeta dist.

Si abrimos el fichero ahora nos encontramos:

:root {
  --color-base-primary: #007bff;
  --color-base-secondary: #00ff00;
  --color-background-button-primary: #007bff;
  --color-background-button-secondary: #00ff00;
  --color-text-primary: #ffffff;
  --color-text-secondary: #333333;
  --size-font-base: 16rem;
  --size-font-medium: 18rem;
  --size-font-large: 24rem;
}

Aquí están nuestros tokens en formato CSS que hemos generado sin apenas esfuerzo. Qué pasada!

Código de ejemplo

Como bien anunciamos al inicio de este post, a continuación os dejamos el repositorio en Github con el código del ejemplo de hoy. Os instamos a que leáis el README.md porque en él encontraréis las instrucciones para ejecutarlo.

El proyecto es compatible con Windows/Linux/Mac sin realizar ninguna configuración adicional. Lo único necesario es tener NodeJS 18.15 o superior instalado en el sistema y acceso a una terminal para ejecutar comandos.

https://github.com/nidstang/style-dictionary-basic

Conclusión

Como puedes ver style-dictionary es una herramienta superversátil y fácil de utilizar. En pocos pasos hemos generado un fichero CSS con custom properties a partir de nuestros tokens.

Las posibilidades de esta herramienta son muchas, suscríbete a nuestra newsletter para no perderte nada.

Si quieres ver más contenido así en el futuro, déjadnos un like :).