Passer au contenu principal

Style des composants personnalisés

Le mécanisme de transformation des jetons de conception peut être utilisé pour appliquer un thème aux composants Jutro de la configuration de base et aux composants et éléments personnalisés spécifiques à l’application.

Pour personnaliser le style des composants fournis par Jutro Design System, il vous suffit de suivre les étapes décrites sur cette page. Jutro inclut tous les mappages nécessaires pour que les jetons de conception fonctionnent de manière transparente avec ses composants, de sorte qu’aucune configuration supplémentaire n’est requise.

Vous pouvez personnaliser des composants et des éléments dans votre application à l’aide des méthodes suivantes :

  1. Définissez des jetons de conception personnalisés, qui généreront des variables CSS personnalisées à utiliser dans votre application.

  2. Mappez des jetons de conception Jutro (« jds ») aux variables CSS personnalisées.

  3. Utilisez directement les variables CSS --JDS- générées.

Warning: Considérations particulières lors de l’utilisation de mappages personnalisés et de variables CSS générées pour adapter le style de vos éléments personnalisés.

  • Si vous utilisez un jeton de conception « jds » dans vos mappages personnalisés, assurez-vous que le jeton de conception correspondant est présent lors de la génération du thème.

  • Si vous faites référence à des variables --JDS- dans votre code, assurez-vous que le jeton de conception correspondant est présent lors de la génération du thème.

  • Les jetons de conception sous l’espace de noms « jds » font partie de la surface de l'API officielle de Jutro et sont couverts par la politique de modifications sans rupture (NBC). Toutefois, les variables CSS générées automatiquement à partir de ces jetons (avec le préfixe --JDS-) ne font pas partie de la surface de l’API et ne sont pas garanties dans le cadre de la stratégie NBC.

  • Chaque variable CSS générée n’est disponible que s’il existe un jeton de conception correspondant. Pour en savoir plus, reportez-vous à la section Modèle de dénomination des jetons de conception en variable CSS.

  • Les composants Jutro Design System utilisent des variables --JDS- en interne. Ces variables internes peuvent changer sans que cela soit considéré comme une modification majeure. Cependant, les jetons de conception « jds » au sein des composants (et la façon dont ils sont appliqués) sont stables et respectent la politique NBC.

Vous trouverez plus d'informations sur la surface de l'API de Jutro ici.

Jetons personnalisés​

Les concepteurs UX peuvent créer un ensemble de jetons personnalisés à utiliser dans l'application. Ces jetons doivent être ajoutés sous un espace de noms différent de « jds » ; par exemple, cela peut être « my-custom-application ».

{
  "my-custom-application": {
    "some-component": {
      "color": {
        "background": {
          "value": "{jds.color.background.neutral}",
          "type": "color",
          "description": "Background color for SomeComponent"
        },
        "text": {
          "value": "#fff",
          "type": "color",
          "description": "Text color for SomeComponent"
        }
      }
    }
  }
}

Les jetons de conception personnalisés peuvent tous être ajoutés dans un seul fichier ou divisés entre plusieurs fichiers : le mécanisme de transformation de jetons de conception en variables CSS transforme tous les jetons de conception d'un répertoire spécifié, de sorte que le nombre de fichiers n'a pas d'importance. Les deux seules règles sont les suivantes :

  1. Deux jetons ne peuvent pas avoir le même chemin dans un même répertoire
  2. Tous les jetons référencés doivent également être définis dans le répertoire de thème

Cela signifie que les jetons personnalisés peuvent faire référence aux jetons de conception Jutro Design System dans leurs valeurs, mais uniquement si les définitions de jetons « jds » sont également stockées dans le même répertoire.

Modèle de dénomination des variables CSS​

Tous les jetons de conception seront transformés en variables CSS selon la convention suivante :

  1. Tous les points . seront remplacés par des tirets -
  2. Toutes les lettres seront en majuscules
  3. Deux tirets -- seront ajoutés au début

Par exemple, un jeton avec le chemin d'accès my-custom-application.some-component.color.background sera transformé en --MY-CUSTOM-APPLICATION-SOME-COMPONENT-COLOR-BACKGROUND.

Les jetons de typographie constituent une exception à cette règle. Étant donné que les jetons de typographie sont des jetons composites, ils doivent être divisés en plusieurs variables CSS distinctes au cours du processus de transformation. Voici un exemple de jeton typographique :

{
  "my-custom-application": {
    "font": {
      "heading-1": {
        "value": {
          "fontFamily": "'Source Sans 3', 'Helvetica', 'Arial', sans-serif",
          "fontWeight": "600",
          "lineHeight": "40px",
          "fontSize": "32px",
          "letterSpacing": "0",
          "paragraphSpacing": "0",
          "textCase": "none",
          "textDecoration": "none"
        },
        "type": "typography",
        "description": "Font properties for heading 1 text"
      }
    }
  }
}

my-custom-application.font.heading-1 sera transformé en variables CSS suivantes :

--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-FAMILY: 'Source Sans 3', 'Helvetica', 'Arial', sans-serif;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-SIZE: 32px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-WEIGHT: 600;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LETTER-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LINE-HEIGHT: 40px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-PARAGRAPH-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-CASE: none;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-DECORATION: none;

Mappages personnalisés​

Il n'est pas nécessaire de créer un tout nouvel ensemble de jetons de conception personnalisés pour générer des variables CSS personnalisées, vous pouvez utiliser la fonctionnalité d'ajout de mappages personnalisés à la place. Pour ce faire, vous devez créer un nouveau fichier json, par exemple customMappings.json, et le remplir avec des paires variable CSS/jeton de conception. N'oubliez pas que tous les jetons référencés doivent être ajoutés au répertoire de thème spécifié.

Exemple de mappage :

{
  "--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR": "jds.color.background.error",
  "--CUSTOM-BUTTON-TEXT-COLOR": "jds.color.text.regular"
}

Vous devrez également ajouter une nouvelle entrée custom-mappings à votre .themesConfig.json. Vous trouverez plus d'informations .themesConfig.json ici.

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

Après l'exécution du processus de transformation, les variables définies dans le mappage sont ajoutées au fichier tokenOverrides.css.

/**
 * 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;
--JDS-COLOR-BACKGROUND-ERROR: #012345;
--JDS-COLOR-TEXT-REGULAR: #28333f;
...
--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR: var(--JDS-COLOR-BACKGROUND-ERROR);
--CUSTOM-BUTTON-TEXT-COLOR: var(--JDS-COLOR-TEXT-REGULAR);
}
Warning: Guidewire fournit le mappage de chaque jeton de conception Guidewire sur la variable CSS Guidewire. N'utilisez pas de mappages personnalisés pour remplacer ou modifier des variables --JDS-. Les variables CSS ne font pas partie de la surface de l'API, elles changent donc entre les versions et votre mappage personnalisé peut être interrompu.
Note: Tous les styles de composant ne sont pas définis à l’aide de jetons de conception : certains composants utilisent des valeurs codées en dur ou des variables CSS avec des valeurs codées en dur (préfixées par --JDS-) à la place. Si vous avez besoin de modifier l’un de ces styles qui ne correspondent pas à des jetons, contactez notre équipe. Nous évaluerons si de nouveaux jetons de conception doivent être créés pour répondre à vos besoins.

Transformations personnalisées​

Dans certains cas, la transformation d'une valeur de jeton de conception en une valeur de variable CSS n'est pas directe et nécessite une logique spécifique pour obtenir la ou les valeurs à déterminer. À cette fin, Guidewire fournit un ensemble de transformations prédéfinies qui couvrent les transformations de base des bordures, de la typographie, des ombres, des calculs, etc. Si vous avez besoin de transformations supplémentaires, vous pouvez écrire une fonction de transformation personnalisée et la transmettre au processus de transformation par un entrée custom-transformations dans .themesConfig.json. Vous trouverez plus d'informations .themesConfig.json ici.

L'extrait suivant montre des exemples de transformations de valeur et de nom personnalisées :

module.exports = {
  customValueTransform: {
    type: 'value',
    transitive: true,
    matcher: token => token.type === 'my-type',
    transformer: token => `"Value of my token: ${token.value}"`
  },
  customNameTransform: {
    type: 'name',
    transformer: token => `CUSTOM-PREFIX-${token.path.join('-').toUpperCase()}`
  }
};

Pour en savoir plus sur l'écriture de transformations personnalisées, reportez-vous à la documentation du dictionnaire de style.

Warning: Les transformations personnalisées s'appliquent uniquement aux jetons personnalisés, qui sont des jetons dont le préfixe est différent de jds. Si aucune transformation personnalisée correspondant à un jeton personnalisé donné n'est définie, le jeton est ensuite transformé à l'aide des transformations Jutro, tant que ce type de jeton est géré par Jutro. Il n'est pas possible de remplacer la transformation des jetons jds.

Voici la liste des types de jetons de conception gérés par Jutro :

  • 'sizing'
  • 'spacing'
  • 'borderRadius'
  • 'borderWidth'
  • 'fontSizes'
  • 'letterSpacing'
  • 'paragraphSpacing'
  • 'dimension'
  • 'typography'
  • 'boxShadow'
  • 'border'
  • 'composition'
  • 'fontFamilies'
  • 'lineHeights'

S'il manque une transformation, informez votre représentant Guidewire que vous en avez besoin afin qu'il puisse envisager de l'ajouter dans une version ultérieure.