Saltar al contenido principal

Transformación a variables CSS

Los tokens de diseño proporcionan un lenguaje común para que los diseñadores y desarrolladores comuniquen sus decisiones de diseño. Los tokens de diseño deben transformarse en variables CSS para que la aplicación funcione con la definición del tema. Guidewire proporciona un comando de transformación basado en el diccionario de estilo para manejar esta transformación, incluida la lógica de transformación predefinida para todos los tokens de diseño definidos por Guidewire.

En este documento, se explica cómo funciona la transformación de tokens de diseño a variables CSS, una vez que el diseñador entrega los tokens definidos a un desarrollador.

Warning: La disponibilidad de cada variable CSS generada depende de la existencia de un token de diseño coincidente o de la definición de una asignación personalizada. Para obtener más información sobre cómo usar tokens para aplicar estilo a componentes personalizados, consulte la página Cómo aplicar estilos a componentes personalizados.

Proceso general para trabajar con tokens de diseño​

  1. El diseñador de UX define los tokens de diseño y sus valores mediante el plugin “Tokens Studio for Figma” (o cualquier otra herramienta compatible).
  2. El diseñador de UX exporta los tokens en un formato JSON y envía el resultado al desarrollador.
  3. El desarrollador convierte los tokens de diseño en variables CSS de modo que se puedan utilizar para controlar la tematización en una aplicación. Este paso se puede realizar de forma manual o automática durante el proceso de compilación de la aplicación. Este proceso de transformación se explica en los próximos párrafos.

Definición de los tokens de diseño y sus valores​

Guidewire proporciona una lista con todos los tokens utilizados por los componentes de Jutro Design System. El diseñador de UX toma esta lista y configura los valores apropiados correspondientes a los requisitos del tema específico.

En caso de que el proyecto requiera la creación de algunos componentes personalizados, se pueden agregar tokens de diseño adicionales a la lista inicial. De esta manera, toda la tematización se manejará de manera unificada, tanto para los componentes proporcionados por Guidewire como para los personalizados.

Exportación de tokens de diseño​

Cuando el diseñador de UX exporta la definición de tokens mediante el plugin “Tokens Studio for Figma”, se crean tres archivos JSON separados correspondientes a cada uno de los tipos de tokens de diseño. A continuación, se muestra un ejemplo de un archivo JSON que contiene tokens de diseño de componentes:

{
  "jds": {
    "color": {
      "background": {
        "neutral": {
          "value": "{jds.color.palette-neutral.20}",
          "type": "color",
          "description": "Neutral background color"
        },
        "neutral-hover": {
          "value": "{jds.color.palette-neutral.30}",
          "type": "color",
          "description": "Neutral background color hover state"
        }
      }
    }
  },
  "custom": {
    "some-component": {
      "color": {
        "background": {
          "value": "{jds.color.background.neutral}",
          "type": "color",
          "description": "Background color for SomeComponent"
        }
      }
    }
  }
}

Preparación de la transformación​

Antes de ejecutar la transformación de los tokens de diseño en variables CSS, asegúrese de cumplir primero los pasos de preparación:

  • Los archivos de definición de token de diseño deben estar disponibles.
  • Los parámetros del proceso de transformación deben estar correctamente configurados.
  • La CLI debe estar instalada.

Agregado de archivos de definición de token de diseño​

Ubique los archivos JSON de token de diseño en la base del código de su aplicación, por ejemplo, en una ubicación como src/tokens/yourThemeName/.... Cada vez que se cree una nueva versión de los tokens de diseño, actualice estos archivos.

Se hará referencia a estos archivos en el archivo de configuración como se explica más adelante en este documento.

Warning: Los desarrolladores nunca deben cambiar los valores de los tokens de diseño en el archivo JSON exportado ni las variables CSS. Un diseñador siempre debe establecer estos valores en el repositorio que contiene la fuente de estos tokens de diseño.

Si está utilizando el método automatizado, inserte estos archivos en el repositorio de código fuente junto con el resto del código y la configuración de la aplicación.

Si utiliza el método manual, no tiene que enviar estos archivos al repositorio de código fuente, ya que no se utilizarán. Sin embargo, se recomienda incluirlos para proporcionar trazabilidad de la versión del token de diseño utilizada para generar el tema.

Archivo .themesConfig.json​

Para que la tematización funcione, debe configurar el archivo .themesConfig.json. Este archivo se crea automáticamente el crear una nueva aplicación de Jutro. También puede usar un comando de la CLI para crearlo; para obtener más información, consulte la sección Generación de .themesConfig.json.

.themesConfig.json contiene lo siguiente:

  • La información sobre el tema que requiere la aplicación.
  • La información que requiere el proceso de transformación de tokens de diseño en variables CSS.

El archivo se parece a lo siguiente:

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "input-path": "src/tokens/sampleTheme/**/*.json",
      "output-file-name": "tokenOverrides.css",
      "custom-mappings": "src/tokens/customMappings.json",
      "custom-transformations": "src/tokens/customTransformations.js"
    }
  }
}

Tenga en cuenta que el archivo .themesConfig.json debe contener todos los temas de su aplicación (si tiene más de uno).

Puede establecer las siguientes propiedades para cada tema definido:

PropiedadUtilizada por definición de temaUtilizada por el proceso de transformaciónDescripción
nameSíSíObligatorio. Nombre para identificar el tema.
tokens/input-pathNoSíObligatorio. Esta es la ruta (relativa a la raíz del proyecto) en la aplicación donde almacenó los tokens.
tokens/output-file-nameSíSíObligatorio. Archivo donde la variable CSS invalida qué resultado de la transformación se almacenará. Este archivo siempre se creará en src/assets/.
tokens/custom-mappingsNoSíAsignación de los tokens a variables CSS personalizadas (ruta relativa a la raíz del proyecto). Encontrará más información aquí.
tokens/custom-transformationsNoSíFunciones de transformación personalizadas para los tipos de tokens personalizados (ruta relativa a la raíz del proyecto). Encontrará más información aquí.

Ejecución de la transformación​

Puede activar el proceso de transformación manualmente o utilizar la opción automatizada. El resultado es el mismo independientemente de la opción que elija: un archivo CSS con variables CSS generadas que se almacena en el archivo de salida predefinido en el directorio assets.

/**
 * Do not edit directly
 * Generated on Mon, 25 Mar 2024 15:35:16 GMT
 */

.themeRoot,
.themeRoot.dynamicRoot {
--JDS-COLOR-BACKGROUND-NEUTRAL: #f0f3f6;
--JDS-COLOR-BACKGROUND-NEUTRAL-HOVER: #dfe5ec;
--CUSTOM-SOME-COMPONENT-COLOR-BACKGROUND: #f0f3f6;
}
Warning: Nunca edite los archivos generados manualmente. Si hay algún problema o falta algo, actualice la definición de los tokens de diseño y vuelva a ejecutar el proceso de transformación.

Transformación manual​

Puede activar la transformación manual ejecutando el script build-themes desde el archivo package.json o el comando de la CLI jutro generate:themes. Esta opción se recomienda principalmente para el modo de desarrollo, ya que permite verificar el resultado de la transformación del tema y su uso en la aplicación.

Consulte la sección “Generación de definiciones de temas para aplicaciones de Jutro” de la documentación de la CLI para obtener más información.

Obtendrá más información sobre el uso de JUTRO_APP_ID en la sección sobre incrustación de un microfrontend en una aplicación shell para la federación de módulos.

Transformación automatizada​

El proceso de transformación se ejecutará automáticamente cuando compile la aplicación una vez que agregue el script "build-themes" : "jutro generate:themes" al archivo package.json. El resultado de la transformación se incluirá en el paquete generado, de modo que esté disponible para que la aplicación lo use.

Warning: El script build-themes debe agregarse antes del script build-webpack en package.json, de lo contrario, no se incluirá en el paquete.
Warning: Si el archivo de salida definido ya contiene una definición de tema, se sobrescribirá durante el proceso de compilación.

Se recomienda la transformación automatizada. Tener el proceso de transformación ejecutado durante el proceso de compilación de la aplicación garantiza que el tema generado esté actualizado y utilice las variables CSS más recientes. Esto facilitará la actualización de la aplicación sin esfuerzo y sin necesidad de intervención manual.

Generación de .themesConfig.json​

Si ejecuta el comando de la CLI jutro generate:themes, pero no se encuentra el archivo .themesConfig.json, el proceso le permite crear un nuevo archivo de configuración.

Consulte la sección “Generación de definiciones de temas para aplicaciones de Jutro” de la documentación de la CLI para obtener más información.

Transformación de los tokens de diseño de altura de línea​

Los tokens de diseño de altura de línea se pueden definir como tokens independientes de tipo lineHeights, donde el valor representa directamente la altura de la línea, o como parte de tokens de typography compuestos, donde lineHeight se especifica junto con otras propiedades de fuente como fontSize.

Sus transformaciones siguen reglas específicas según la unidad y el tipo:

Alturas de línea sin unidades​

Independientemente del tipo de definición de altura de línea, las alturas de línea sin unidades se tratan como valores de píxel y px se agrega al valor durante el proceso de transformación. Por ejemplo, si el valor de un token de diseño es 14, el valor de la variable CSS resultante es 14px.

Porcentaje de alturas de línea​
  • Si el token es independiente, del tipo lineHeights, entonces la unidad permanece como %. Por ejemplo, si el valor del token es 80%, el valor de la variable CSS resultante también será 80%.
  • Si el token se especifica con una propiedad lineHeight, como parte de un token compuesto del tipo typography, durante la transformación, el valor de la altura de la línea se calcula en función de la propiedad fontSize. La unidad de la altura de línea calculada coincide con la unidad de la propiedad fontSize. Por ejemplo:
    • Si la propiedad lineHeight se establece en 150% y la propiedad fontSize se establece en 16px, entonces el valor resultante de la variable CSS es 24px.
    • Si la propiedad lineHeight se establece en 125% y la propiedad fontSize se establece en 1rem, entonces el valor resultante de la variable CSS es 1.25rem.
Alturas de línea con otras unidades​

Independientemente del tipo de definición de altura de línea, para otras unidades, la unidad y el valor después de la transformación siguen siendo los mismos que los definidos en el token de diseño. Por ejemplo, si el valor de un token de diseño es 1rem, el valor de la variable CSS resultante es 1rem.