Passer au contenu principal

Transformation en variables CSS

Les jetons de conception fournissent un langage commun aux concepteurs et aux développeurs pour communiquer leurs décisions de conception. Les jetons de conception doivent être transformés en variables CSS pour que l'application fonctionne avec la définition du thème. Guidewire fournit une commande de transformation basée sur le dictionnaire de style pour gérer cette transformation, y compris une logique de transformation prédéfinie pour tous les jetons de conception définis par Guidewire.

Ce document explique comment fonctionne la transformation des jetons de conception en variables CSS, une fois que le concepteur a remis les jetons définis à un développeur.

Warning: La disponibilité de chaque variable CSS générée dépend de l’existence d’un jeton de conception correspondant ou de la définition d’un mappage personnalisé. Pour savoir comment utiliser des jetons pour personnaliser le style des composants, reportez-vous à la page Style des composants personnalisés.

Processus général d'utilisation des jetons de conception​

  1. Le concepteur d'expérience utilisateur définit les jetons de conception et leurs valeurs à l'aide du plug-in « Tokens Studio for Figma » (ou de tout autre outil pris en charge).
  2. Le concepteur d'expérience utilisateur exporte les jetons dans un format JSON et partage le résultat avec le développeur.
  3. Le développeur convertit les jetons de conception en variables CSS afin qu'ils puissent être utilisés pour contrôler les thèmes dans une application. Cette étape peut être effectuée manuellement ou automatiquement pendant le processus de compilation de l'application. Ce processus de transformation est expliqué ci-dessous.

Définition des jetons de conception et de leurs valeurs​

Guidewire fournit une liste de tous les jetons utilisés par les composants Jutro Design System. Le concepteur d'expérience utilisateur utilise cette liste et configure les valeurs appropriées correspondant aux exigences du thème spécifique.

Si le projet nécessite la création de composants personnalisés, des jetons de conception supplémentaires peuvent être ajoutés à la liste initiale. De cette façon, tous les thèmes seront traités de manière unifiée, pour les composants fournis par Guidewire et les composants personnalisés.

Exportation de jetons de conception​

Lorsque le concepteur d'expérience utilisateur exporte la définition des jetons à l'aide du plug-in « Tokens Studio for Figma », trois fichiers JSON distincts correspondant à chacun des types de jetons de conception sont créés. Vous trouverez ci-dessous un exemple de fichier JSON contenant des jetons de conception de composants :

{
  "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"
        }
      }
    }
  }
}

Préparation de la transformation​

Avant d'exécuter la transformation des jetons de conception en variables CSS, assurez-vous de suivre d'abord les étapes de préparation suivantes :

  • Les fichiers de définition des jetons de conception sont disponibles.
  • Les paramètres du processus de transformation sont correctement définis.
  • La CLI est installée.

Ajout de fichiers de définition de jeton de conception​

Placez les fichiers JSON du jeton de conception dans la base de code de votre application, par exemple dans un emplacement tel que src/tokens/yourThemeName/.... Chaque fois qu'une nouvelle version des jetons de conception est créée, mettez à jour ces fichiers.

Ces fichiers seront référencés dans le fichier de configuration comme expliqué plus loin dans ce document.

Warning: Les développeurs ne doivent jamais modifier les valeurs des jetons de conception dans le fichier JSON exporté ou les variables CSS. Un concepteur doit toujours définir ces valeurs dans le référentiel qui contient la source de ces jetons de conception.

Si vous utilisez l'approche automatisée, transmettez ces fichiers au référentiel de code source avec le reste du code de l'application et de la configuration.

Si vous utilisez l'approche manuelle, vous n'avez pas besoin de transmettre ces fichiers au référentiel de code source, car ils ne seront pas utilisés. Toutefois, il est recommandé de les inclure afin de garantir la traçabilité de la version du jeton de conception utilisée pour générer le thème.

Fichier .themesConfig.json​

Pour que le thème fonctionne, vous devez configurer le fichier .themesConfig.json. Ce fichier est créé automatiquement lorsque vous créez une nouvelle application Jutro. Vous pouvez également utiliser une commande d'interface de ligne de commande pour la créer. Pour en savoir plus, reportez-vous à la section Génération de .themesConfig.json.

.themesConfig.json contient les éléments suivants :

  • Informations sur le thème requises par l'application.
  • Informations requises par le processus de transformation des jetons de conception en variables CSS.

Le fichier ressemble à ce qui suit :

{
  "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"
    }
  }
}

Notez que le fichier .themesConfig.json doit contenir tous les thèmes de votre application (s'il en comporte plusieurs).

Vous pouvez définir les propriétés suivantes pour chaque thème défini :

PropriétéUtilisée par la définition du thèmeUtilisée par le processus de transformationDescription
nameOuiOuiObligatoire. Nom pour identifier le thème.
tokens/input-pathNonOuiObligatoire. Il s'agit du chemin (relatif à la racine du projet) dans l'application où vous avez stocké les jetons.
tokens/output-file-nameOuiOuiObligatoire. Le fichier dans lequel les remplacements des variables CSS qui résultent de la transformation seront stockés. Ce fichier sera toujours créé sous src/assets/.
tokens/custom-mappingsNonOuiMappage des jetons sur les variables CSS personnalisées (chemin relatif à la racine du projet). Vous trouverez plus d'informations ici :
tokens/custom-transformationsNonOuiFonctions de transformation personnalisées pour les types de jetons personnalisés (chemin relatif à la racine du projet). Vous trouverez plus d'informations ici :

Exécution de la transformation​

Vous pouvez déclencher le processus de transformation manuellement ou utiliser l'option automatisée. Le résultat est le même, quelle que soit l'option choisie : un fichier CSS avec des variables CSS générées qui est stocké dans le fichier de sortie prédéfini dans le répertoire 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: Ne modifiez jamais manuellement les fichiers générés. En cas d'erreur ou d'élément manquant, mettez à jour la définition des jetons de conception et exécutez à nouveau le processus de transformation.

Transformation manuelle​

Vous pouvez déclencher la transformation manuelle en exécutant le script build-themes à partir du fichier package.json ou de la commande d'interface de ligne de commande jutro generate:themes. Cette option est principalement recommandée pour le mode développement, car elle vous permet de vérifier le résultat de la transformation du thème et son utilisation dans l'application.

Pour en savoir plus, reportez-vous à la section « Générer des définitions de thème pour les applications Jutro » de la documentation CLI.

Pour en savoir plus sur l'utilisation de JUTRO_APP_ID, reportez-vous à la section Intégrer un micro front-end dans une application shell pour la fédération de modules.

Transformation automatisée​

Le processus de transformation s'exécutera automatiquement lorsque vous créerez l'application une fois que vous aurez ajouté le script "build-themes" : "jutro generate:themes" au fichier package.json. Le résultat de la transformation sera inclus dans le lot généré, l'application peut donc l'utiliser.

Warning: Le script build-themes doit être ajouté avant le script build-webpack dans package.json, sinon il ne sera pas inclus dans le lot.
Warning: Si le fichier de sortie défini contient déjà une définition de thème, celle-ci sera écrasée pendant le processus de compilation.

La transformation automatisée est recommandée. L'exécution du processus de transformation pendant le processus de compilation de l'application garantit que le thème généré est à jour et utilise les dernières variables CSS. Cela facilitera la mise à niveau de l'application sans effort et sans intervention manuelle requise.

Génération du fichier .themesConfig.json​

Si vous exécutez la commande CLI jutro generate:themes, mais que le fichier .themesConfig.json est introuvable, le processus vous permet de créer un nouveau fichier de configuration.

Pour en savoir plus, reportez-vous à la section « Générer des définitions de thème pour les applications Jutro » de la documentation CLI.

Transformation des jetons de conception de hauteur de ligne​

Les jetons de conception de hauteur de ligne peuvent être définis soit en tant que jetons autonomes de type lineHeights, où la valeur représente directement la hauteur de ligne, soit en tant que partie de jetons typography composites, où lineHeight est spécifié avec d’autres propriétés de police telles que fontSize.

Leurs transformations suivent des règles spécifiques en fonction de l’unité et du type :

Hauteurs de ligne sans unité​

Quel que soit le type de définition de hauteur de ligne, les hauteurs de ligne sans unité sont traitées comme des valeurs de pixel et px est ajouté à la valeur pendant le processus de transformation. Par exemple, si la valeur d’un jeton de conception correspond à 14, alors la valeur de la variable CSS qui en découle est 14px.

Hauteurs de ligne en pourcentage​
  • Si le jeton est autonome, de type lineHeights, l’unité reste %. Par exemple, si la valeur du jeton correspond à 80%, la valeur de la variable CSS qui en découle sera également 80%.
  • Si le jeton est spécifié avec une propriété lineHeight, dans le cadre d’un jeton composite de type typography, pendant la transformation, la valeur de la hauteur de ligne est calculée en fonction de la propriété fontSize. L’unité de la hauteur de ligne calculée correspond à l’unité de la propriété fontSize. Par exemple :
    • Si la propriété lineHeight est définie sur 150% et la propriété fontSize sur 16px, alors la valeur de la variable CSS qui en découle est 24px.
    • Si la propriété lineHeight est définie sur 125% et la propriété fontSize sur 1rem, alors la valeur de la variable CSS qui en découle est 1.25rem.
Hauteurs de ligne avec d’autres unités​

Quel que soit le type de définition de hauteur de ligne, pour les autres unités, l’unité et la valeur après transformation restent les mêmes que celles définies dans le jeton de conception. Par exemple, si la valeur d’un jeton de conception correspond à 1rem, alors la valeur de la variable CSS qui en découle est 1rem.