Implémentation de thèmes

Jutro est livré avec un mécanisme de thème qui permet d'appliquer un style homogène dans l'ensemble de votre application. Tandis que la partie conception est effectuée via des jetons de conception, l'application nécessite des variables CSS pour gérer la définition des styles. Ces variables CSS résultent de la transformation des jetons de conception en variables CSS. D'autres options de personnalisation sont également disponibles.

Vous pouvez également utiliser des jetons de conception avec des composants personnalisés. Vous devez soit définir de nouveaux jetons de conception pour ces composants personnalisés, soit ajouter un fichier de mappage des jetons existants vers de nouvelles variables CSS à la configuration de transformation. Pour en savoir plus sur la définition des styles des composants personnalisés, cliquez ici.

Note: L'ancien mécanisme de définition des thèmes basé sur la définition manuelle des remplacements de variables CSS --GW- est obsolète, mais il est toujours disponible et pris en charge pour les composants legacy. Passez à une version de la documentation antérieure à la version 10.0 pour afficher plus de détails sur ce mécanisme ou accédez à la page Thèmes hérités pour savoir comment passer à l'utilisation de jetons de conception.

Comment fonctionnent les thèmes Jutro ?

Les thèmes Jutro sont implémentés avec les packages NPM @jutro/theme, @jutro/theme-styles et @jutro/design-tokens. Toutefois, dans la plupart des cas, vous n'avez pas à y faire référence directement.

Généralement, vous créez votre application avec la méthode start() qui vient de @jutro/app. Ce lanceur enveloppe votre application avec un composant racine <ThemeProvider> qui applique les thèmes. Si vous ne fournissez aucune configuration de thème à la méthode start(), le thème (Enterprise) par défaut est utilisé.

Les thèmes, au niveau de l'implémentation, reposent sur des variables CSS globales qui définissent des valeurs CSS communes pour divers aspects de l'apparence. Certains s'appliquent à des composants individuels, d'autres s'appliquent à des groupes entiers de composants. Ces valeurs de variables sont mappées à partir des jetons de conception définis pendant le processus de transformation.

Chaque variable fournie par Jutro est nommée selon l'une de ces deux conventions (tout en majuscules) :

# CSS variables generated from design tokens
--JDS-[<CATEGORY>]-[<PROPERTY>]-[<MODIFIER>]

# legacy option still applied in many components
--GW-[<OPTIONAL-COMPONENT-OR-GROUP-NAME>]-<STYLING-ASPECT>-[<OPTIONAL-VARIANT>]

Exemples :

--JDS-COLOR-BACKGROUND-BRAND
--JDS-COLOR-BACKGROUND-ERROR-SUBTLE
--GW-ACCORDION-BORDER-FOCUS
--GW-FOCUS-ERROR-COLOR-DARK

Warning: N'utilisez pas les variables CSS --JDS- définies par Guidewire pour définir le style des composants personnalisés. Les variables CSS générées à partir de jetons sous l'espace de noms « jds » ne font PAS partie de la surface de l'API et ne sont PAS couvertes par la politique de modifications sans rupture (NBC). Cela signifie que toutes les variables CSS commençant par --JDS- peuvent changer de nom/valeur entre les versions. Nous vous déconseillons donc fortement de les utiliser pour définir le style des applications. Utilisez plutôt l'une des méthodes mentionnées ici.

À faire et à ne pas faire en matière de thème

Si vous suivez les limites décrites sur cette page, votre thème sera plus facile à gérer et à mettre à niveau. Vous trouverez ci-dessous une synthèse des limites :

Pour ajuster les styles Jutro globalement, utilisez des jetons de conception.
N'utilisez que des parties de Jutro Design System qui appartiennent à notre surface d'API
Ne modifiez aucune des définitions de variables CSS générées manuellement.
N'utilisez pas de variables CSS --JDS- pour personnaliser des composants, suivez les approches recommandées.
Lors de la définition des styles, ne vous fiez pas aux détails d'implémentation internes des composants, y compris les variables CSS.
N'utilisez jamais la force brute ou le hacking de styles en rédigeant des sélecteurs complexes pour faire correspondre les composants d'une page. Par exemple, ne faites pas correspondre « le premier bouton du formulaire ».

Personnalisation des styles Jutro et maintien de la possibilité mise à niveau

Le moyen officiellement pris en charge pour personnaliser les composants Jutro est l'utilisation de jetons de conception et le résultat de leur transformation en variables CSS.

Si, à la suite d'une modification de composant, les variables CSS --JDS- qu'un composant utilise changent, Guidewire inclura les modifications requises dans la configuration du jeton de conception au processus de transformation de variable CSS pour permettre la mise à niveau vers la nouvelle version sans aucun effet négatif ni intervention manuelle de l'utilisateur.

Configurer un thème personnalisé pour votre application

Le meilleur moyen de remplacer les styles de manière globale est de créer un thème personnalisé. Par défaut, les applications Jutro utilisent le thème « Enterprise ». Pour passer à un autre thème, procédez comme suit :

Préparez la configuration des jetons de conception pour votre thème personnalisé. Le processus est décrit sur cette page.
Transmettez le bon thème à la fonction start dans ./src/startApp.js :

import themesConfig from './.themesConfig.json';

start(Jutro, {
        ...
        themeConfig: themesConfig.sampleTheme,
    });

Consultez les pages de documentation des jetons de conception pour en savoir plus.

Accéder aux thèmes externes

À la fin, après toutes les transformations, la définition de votre thème est stockée dans le fichier tokenOverrides.css (ou tout autre nom donné) contenant les valeurs de variables CSS mappées à partir des jetons de conception. Comme le lien vers ce fichier est repris de la configuration du thème et utilisé comme valeur href dans une balise HTML <link>, vous pouvez placer le fichier CSS sur un autre serveur. Dans ce cas, dans votre .themesConfig.json, vous n'avez pas besoin d'indiquer input-path car vous n'exécutez aucune transformation localement. Il vous suffira d'ajouter le lien vers votre fichier tokenOverrides.css sous la forme d'une valeur de output-file-name.

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "output-file-name": "https://example.com/theme/tokenOverrides.css"
    }
  }
}

Vous pouvez utiliser cela pour exécuter les scénarios suivants :

Partager le thème personnalisé entre différentes applications
Déployer de nouveaux thèmes indépendamment de l'application

Notez toutefois que les fichiers doivent être disponibles dans le navigateur du client et que la mise en cache peut empêcher le navigateur du client d'afficher instantanément les styles mis à jour.

Notez également que les fichiers distants ne sont pas migrés automatiquement pendant la mise à niveau.

Personnalisation des styles d'une instance unique d'un composant Jutro

Vous pouvez utiliser une propriété className pour personnaliser l'aspect et la convivialité d'une instance individuelle d'un composant Jutro.

Préparez votre classe CSS personnalisée :

.myCustomButtonStyles {
  background: red;
}

Copiez-la dans le composant à l'aide de la propriété className :

import { Button } from '@jutro/component';
import styles from './myStyles.module.scss';

const MyForm = () => {
  // this instance of button is going to have use our red background instead of the default one
  return <Button className={styles.myCustomButtonStyles}>Get insured!</Button>;
};

N'essayez pas de remplacer les styles par défaut des composants Jutro en extrayant les noms des classes CSS fournies par Jutro et en les remplaçant directement dans vos feuilles de style. Si vous faites référence à une classe Jutro directement, vos personnalisations cesseront de fonctionner au cas où Jutro passe à un mécanisme de hachage différent ou renomme la classe. Les noms de classe ne font pas partie de la surface de l'API Jutro et leurs noms peuvent changer entre les différentes versions.

.jut__Button__button {
  //this is WRONG, please do not do this
  background: red;
}

Polices, images, fichiers statiques

Toutes les ressources statiques se trouvent généralement dans votre dossier src/assets. Vous pouvez les référencer comme suit :

à partir de modèles HTML à l'aide du préfixe générique %PUBLIC_URL%, par exemple :
```
<img src="%PUBLIC_URL%/<path-to-the-image-under-src-assets>" />
```

à partir du code JS (par exemple, dans le rendu du composant), à l'aide de la variable d'environnement PUBLIC_URL :

render() {
    return (
        <img src={`${process.env.PUBLIC_URL}/<path-to-the-image-under-src-assets>`} />
    );
}

à partir de fichiers CSS à l'aide d'un chemin absolu ou relatif : dans ce cas, le navigateur recherche les fichiers relatifs au fichier CSS où le lien est spécifié

Ajout de polices personnalisées

Pour appliquer une police personnalisée, placez-la dans votre dossier src/assets/fonts et ajoutez-la dans votre fichier SCSS.

@font-face {
  font-family: Acme;
  src: url(./assets/fonts/Acme-Regular.ttf);
}

Vous pouvez appliquer la police à n'importe quel composant ou classe. Si vous souhaitez remplacer la police d'un thème, remplacez le jeton de conception approprié.

Polices dans webpack 5

Lorsque vous passez à webpack 5, votre fichier Theme.scss doit contenir uniquement des polices, comme indiqué ci-dessous :

Theme.scss
$fonts-root: '~@jutro/theme/assets/fonts';

// ------------------------------------
//   GROUNDED CSS MODULES
// ------------------------------------
@import '~@jutro/theme/assets/fonts/fonts';

Nous vous déconseillons d'ajouter d'autres informations à votre fichier Theme.scss.

Gérer les différences de thèmes en fonction des points d’arrêt

Jutro ne fournit pas de fonction personnalisée pour gérer les différences de thème en fonction des points d’arrêt, mais vous pouvez utiliser des mécanismes CSS intégrés, tels que des requêtes multimédias, si ce comportement est requis pour votre application.

La section suivante est un exemple d’une façon de procéder, mais une approche différente peut être nécessaire en fonction de la nature de votre application.

Utilisation de requêtes de support CSS pour gérer les différences de thème en fonction des points d’arrêt

Dans cette approche, vous utiliserez des requêtes de média CSS pour déterminer quel ensemble de jetons de conception est actif en fonction de la largeur de la fenêtre d’affichage et s’il est affiché sur un périphérique à l’écran. Votre cas d’utilisation peut nécessiter la définition de plusieurs scénarios, mais cet exemple en couvre deux :

screen and (min-width: 769px) : actif lors de l’affichage sur un périphérique à écran et si la largeur est d’au moins 769 pixels.
screen and (max-width: 768px) : actif lors de l’affichage sur un périphérique à écran et si la largeur est inférieure ou égale à 768 pixels.

Voici une synthèse rapide des étapes à suivre :

Définissez un thème à l’aide de jetons de conception pour chaque scénario.
Générez les fichiers CSS pour vos thèmes à l’aide de la CLI Jutro.
Créez manuellement un fichier CSS qui importe les fichiers CSS générés et utilise des requêtes média pour définir lequel des fichiers est actif.
Créez un thème qui utilise le fichier CSS créé manuellement.

Considérations relatives à l’utilisation de cette approche

Avec cette approche, chaque fois que les thèmes sont régénérés, le nouveau thème d’encapsulation combiné reflète automatiquement les modifications sans aucune autre étape.

Le lot inclut tous les thèmes susceptibles d’avoir un impact sur l’utilisation du réseau et les temps de chargement.
Bien que cela nécessite de créer manuellement un thème, il s’agit d’une action unique. Si vous apportez des modifications aux thèmes enfants, il vous suffit de réexécuter la commande jutro generate:themes et vous n’aurez pas besoin de mettre à jour à nouveau votre fichier créé manuellement.
Cette recommandation est basée sur le cas où les deux définitions de thème importées contiennent des thèmes complets, et aucune n’est un remplacement partiel de certaines variables ou valeurs. Pour cette raison, les deux importations utilisent la condition de largeur. Cela permet :
- D'avoir un seul thème actif pour l’évaluation CSS.
- De n'avoir aucun conflit en cascade (par exemple, un !important dans le thème de base appliqué à la valeur définie dans le remplacement de média).
- D'avoir une séparation complète entre les thèmes.
- Il est possible que le thème de base soit appliqué avant le thème réactif si les utilisateurs ont des connexions réseau lentes ou peu fiables.

Instructions sur la façon d’appliquer cette approche dans une application Jutro

Définissez vos thèmes à l’aide de jetons de conception et importez-les dans le fichier .themesConfig.json comme vous le feriez normalement. Pour en savoir plus, reportez-vous à la documentation sur la transformation en variables CSS.
Exécutez la commande jutro generate:themes pour générer les fichiers contenant les variables CSS pour vos thèmes, comme vous le feriez normalement. Pour en savoir plus sur cette commande, reportez-vous à la documentation sur la CLI.
Définissez manuellement un nouveau thème dans votre répertoire styles, sans jetons, qui combine chaque thème de point d’arrêt par le biais d’importations dans un fichier nommé comme Combined-Themes/combined-themes-design-tokens.css. Par exemple, si vos thèmes sont nommés ConsumerDesktop et ConsumerTablet, vous ajoutez alors le texte suivant :

styles/Combined-Themes/combined-themes-design-tokens.css
@import url('../Consumer-Desktop/consumer-desktop-design-tokens.css') screen and
  (min-width: 769px);
@import url('../Consumer-Tablet/consumer-tablet-design-tokens.css') screen and
  (max-width: 768px);

Ajoutez le thème combiné au .themesConfig.json en tant que remplacement de variable.

  "CombinedThemes": {
  "name": "CombinedThemes",
  "variableOverrides":"styles/Combined-Themes/combined-themes-design-tokens.css"
}

Note:

Vous n’avez pas besoin de réexécuter jutro generate:themes par la suite comme dans à l'étape 2, car vous avez créé manuellement le fichier CSS que ce thème utilise à l’étape 3.

Dans votre fichier startApp, mettez à jour l’argument themeConfig de la fonction start pour utiliser votre nouveau thème CombinedThemes :

start(Jutro, {
  ...
  themeConfig: themesConfig.CombinedThemes,
  ...
});

Une démonstration détaillée de ce processus est décrite dans la mission d’apprentissage portant sur l’ajout de thèmes de point d’arrêt.

Comment fonctionnent les thèmes Jutro ?​

À faire et à ne pas faire en matière de thème​

Personnalisation des styles Jutro et maintien de la possibilité mise à niveau​

Configurer un thème personnalisé pour votre application​

Accéder aux thèmes externes​

Personnalisation des styles d'une instance unique d'un composant Jutro​

Polices, images, fichiers statiques​

Ajout de polices personnalisées​

Polices dans webpack 5​

Gérer les différences de thèmes en fonction des points d’arrêt​

Utilisation de requêtes de support CSS pour gérer les différences de thème en fonction des points d’arrêt​

Considérations relatives à l’utilisation de cette approche​

Instructions sur la façon d’appliquer cette approche dans une application Jutro​

Comment fonctionnent les thèmes Jutro ?

À faire et à ne pas faire en matière de thème

Personnalisation des styles Jutro et maintien de la possibilité mise à niveau

Configurer un thème personnalisé pour votre application

Accéder aux thèmes externes

Personnalisation des styles d'une instance unique d'un composant Jutro

Polices, images, fichiers statiques

Ajout de polices personnalisées

Polices dans webpack 5

Gérer les différences de thèmes en fonction des points d’arrêt

Utilisation de requêtes de support CSS pour gérer les différences de thème en fonction des points d’arrêt

Considérations relatives à l’utilisation de cette approche

Instructions sur la façon d’appliquer cette approche dans une application Jutro