Comment Nordhealth utilise-t-elle les propriétés personnalisées de ses composants Web ?

Avantages de l'utilisation de propriétés personnalisées dans les systèmes de conception et les bibliothèques de composants

David Darnes
David Darnes

Je m'appelle Dave et je suis développeur front-end senior chez Nordhealth. Je travaille sur la conception et le développement de notre système de conception Nord, qui comprend la création de composants Web pour notre bibliothèque de composants. Je voulais vous expliquer comment nous avons résolu les problèmes liés au style des composants Web à l'aide des propriétés personnalisées CSS, ainsi que certains des autres avantages de l'utilisation de ces propriétés dans les systèmes de conception et les bibliothèques de composants.

Comment nous créons des composants Web

Pour créer nos composants Web, nous utilisons Lit, une bibliothèque qui fournit beaucoup de code standard, comme l'état, les styles de portée, la création de modèles, etc. Lit est non seulement léger, mais il est également basé sur des API JavaScript natives. Nous pouvons ainsi fournir un bundle de code allégé qui exploite les fonctionnalités déjà disponibles dans le navigateur.


import {html, css, LitElement} from 'lit';

export class SimpleGreeting extends LitElement {
  static styles = css`:host { color: blue; font-family: sans-serif; }`;

  static properties = {
    name: {type: String},
  };

  constructor() {
    super();
    this.name = 'there';
  }

  render() {
    return html`

Hey ${this.name}, welcome to Web Components!

`
; } } customElements.define('simple-greeting', SimpleGreeting);
Composant Web écrit avec Lit.

Mais l'aspect le plus intéressant des composants Web est qu'ils fonctionnent avec presque tous les frameworks JavaScript existants, voire sans framework du tout. Une fois le package JavaScript principal référencé dans la page, l'utilisation d'un composant Web ressemble beaucoup à celle d'un élément HTML natif. Le seul signe révélateur qu'il ne s'agit pas d'un élément HTML natif est le trait d'union dans les balises, qui est une norme pour indiquer au navigateur qu'il s'agit d'un composant Web.

Encapsulation de style Shadow DOM

Tout comme les éléments HTML natifs disposent d'un Shadow DOM, les Web Components en ont également un. Le Shadow DOM est un arbre de nœuds masqué dans un élément. Le meilleur moyen de visualiser cela est d'ouvrir l'outil d'inspection du navigateur et d'activer l'option "Afficher l'arborescence DOM de l'ombre". Une fois cette opération effectuée, essayez d'examiner un élément de saisie natif dans l'inspecteur. Vous pouvez désormais ouvrir cette saisie et voir tous les éléments qu'elle contient. Vous pouvez même essayer cela avec l'un de nos composants Web. Essayez d'inspecter notre composant de saisie personnalisé pour voir son Shadow DOM.

Le Shadow DOM inspecté dans les outils de développement
Exemple de Shadow DOM dans un élément de saisie de texte standard et dans notre composant Web de saisie Nord.

L'encapsulation de style est l'un des avantages (ou inconvénients, selon votre point de vue) du Shadow DOM. Si vous écrivez du code CSS dans votre composant Web, ces styles ne peuvent pas s'échapper et affecter la page principale ou d'autres éléments. Ils sont complètement contenus dans le composant. De plus, le CSS écrit pour la page principale ou un composant Web parent ne peut pas s'infiltrer dans votre composant Web.

Cette encapsulation des styles est un avantage dans notre bibliothèque de composants. Cela nous garantit davantage que lorsqu'un utilisateur utilise l'un de nos composants, il aura l'apparence souhaitée, quels que soient les styles appliqués à la page parente. Pour nous en assurer, nous ajoutons all: unset; à la racine, ou "hôte", de tous nos composants Web.


:host {
  all: unset;
  display: block;
  box-sizing: border-box;
  text-align: start;
  /* ... */
}
Certains codes standards de composants sont appliqués à la racine d'ombre ou au sélecteur d'hôte.

Toutefois, que se passe-t-il si un utilisateur de votre composant Web a une raison légitime de modifier certains styles ? Peut-être qu'une ligne de texte doit être plus contrastée en raison de son contexte, ou qu'une bordure doit être plus épaisse ? Si aucun style ne peut pénétrer dans votre composant, comment pouvez-vous déverrouiller ces options de style ?

C'est là que les propriétés personnalisées CSS entrent en jeu.

Propriétés CSS personnalisées

Les propriétés personnalisées sont très bien nommées. Il s'agit de propriétés CSS que vous pouvez nommer entièrement et auxquelles vous pouvez appliquer la valeur souhaitée. La seule exigence est de les préfixer de deux traits d'union. Une fois que vous avez déclaré votre propriété personnalisée, vous pouvez utiliser sa valeur dans votre CSS à l'aide de la fonction var().


:root {
  --n-color-accent: rgb(53, 89, 199);
  /* ... */
}

.n-color-accent-text {
  color: var(--n-color-accent);
}
Exemple de notre framework CSS d'un jeton de conception en tant que propriété personnalisée et de son utilisation dans une classe d'assistance.

En ce qui concerne l'héritage, toutes les propriétés personnalisées sont héritées, ce qui suit le comportement habituel des propriétés et valeurs CSS standards. Toute propriété personnalisée appliquée à un élément parent ou à l'élément lui-même peut être utilisée comme valeur pour d'autres propriétés. Nous utilisons beaucoup les propriétés personnalisées pour nos jetons de conception en les appliquant à l'élément racine via notre framework CSS. Cela signifie que tous les éléments de la page peuvent utiliser ces valeurs de jeton, qu'il s'agisse d'un composant Web, d'une classe d'assistance CSS ou d'un développeur qui souhaite extraire une valeur de notre liste de jetons.

Cette capacité à hériter des propriétés personnalisées, à l'aide de la fonction var(), nous permet de percer le Shadow DOM de nos composants Web et de donner aux développeurs un contrôle plus précis lors de la mise en forme de nos composants.

Propriétés personnalisées dans un composant Web Nord

Chaque fois que nous développons un composant pour notre système de conception, nous adoptons une approche réfléchie pour son CSS. Nous souhaitons obtenir un code allégé, mais très facile à gérer. Les jetons de conception que nous avons sont définis en tant que propriétés personnalisées dans notre framework CSS principal sur l'élément racine.


:root {
  --n-space-m: 16px;
  --n-space-l: 24px;
  /* ... */
  --n-color-background: rgb(255, 255, 255);
  --n-color-border: rgb(216, 222, 228);
  /* ... */
}
Propriétés personnalisées CSS définies sur le sélecteur racine.

Ces valeurs de jeton sont ensuite référencées dans nos composants. Dans certains cas, nous appliquerons la valeur directement à la propriété CSS, mais dans d'autres, nous définirons une nouvelle propriété personnalisée contextuelle et y appliquerons la valeur.


:host {
  --n-tab-group-padding: 0;
  --n-tab-list-background: var(--n-color-background);
  --n-tab-list-border: inset 0 -1px 0 0 var(--n-color-border);
  /* ... */
}

.n-tab-group-list {
  box-shadow: var(--n-tab-list-border);
  background-color: var(--n-tab-list-background);
  gap: var(--n-space-s);
  /* ... */
}
Propriétés personnalisées définies sur la racine d'ombre du composant, puis utilisées dans les styles du composant. Les propriétés personnalisées de la liste des jetons de conception sont également utilisées.

Nous allons également extraire certaines valeurs spécifiques au composant, mais qui ne figurent pas dans nos jetons, et les transformer en propriété personnalisée contextuelle. Les propriétés personnalisées contextuelles du composant présentent deux avantages clés. Tout d'abord, cela signifie que nous pouvons être plus "simplifiés" avec notre CSS, car cette valeur peut être appliquée à plusieurs propriétés dans le composant.


.n-tab-group-list::before {
  /* ... */
  padding-inline-start: var(--n-tab-group-padding);
}

.n-tab-group-list::after {
  /* ... */
  padding-inline-end: var(--n-tab-group-padding);
}
Propriété personnalisée contextuelle de marge intérieure du groupe d'onglets utilisée à plusieurs endroits dans le code du composant.

Deuxièmement, cela permet de modifier de manière très claire l'état et les variations du composant. Seule la propriété personnalisée doit être modifiée pour mettre à jour toutes ces propriétés lorsque, par exemple, vous stylisez un état de survol ou actif, ou, dans ce cas, une variation.


:host([padding="l"]) {
  --n-tab-group-padding: var(--n-space-l);
}
Variante du composant d'onglet dans laquelle la marge intérieure est modifiée à l'aide d'une seule mise à jour de propriété personnalisée plutôt que de plusieurs mises à jour.

Mais l'avantage le plus intéressant est que lorsque nous définissons ces propriétés personnalisées contextuelles sur un composant, nous créons une sorte d'API CSS personnalisée pour chacun de nos composants, que l'utilisateur de ce composant peut exploiter.


<nord-tab-group label="Title">
  <!-- ... -->
</nord-tab-group>

<style>
  nord-tab-group {
    --n-tab-group-padding: var(--n-space-xl);
  }
</style>
En utilisant le composant de groupe d'onglets sur la page et en définissant la propriété personnalisée de marge intérieure sur une taille plus grande.

L'exemple précédent montre l'un de nos composants Web avec une propriété personnalisée contextuelle modifiée via un sélecteur. Le résultat de cette approche est un composant qui offre à l'utilisateur une flexibilité suffisante pour le style, tout en gardant la plupart des styles réels sous contrôle. De plus, en tant que développeurs de composants, nous pouvons intercepter les styles appliqués par l'utilisateur. Si nous souhaitons ajuster ou étendre l'une de ces propriétés, nous pouvons le faire sans que l'utilisateur ait à modifier son code.

Nous trouvons cette approche extrêmement efficace, non seulement pour nous en tant que créateurs de nos composants de système de conception, mais aussi pour notre équipe de développement lorsqu'elle utilise ces composants dans nos produits.

Exploiter pleinement les propriétés personnalisées

Au moment de la rédaction de cet article, nous ne divulguons pas ces propriétés personnalisées contextuelles dans notre documentation. Nous prévoyons toutefois de le faire afin que notre équipe de développement puisse les comprendre et les exploiter. Nos composants sont empaquetés sur npm avec un fichier manifeste, qui contient tout ce que vous devez savoir à leur sujet. Nous utilisons ensuite le fichier manifeste en tant que données lorsque notre site de documentation est déployé, ce qui se fait à l'aide d'Eleventy et de sa fonctionnalité de données globales. Nous prévoyons d'inclure ces propriétés personnalisées contextuelles dans ce fichier de données de fichier manifeste.

Nous souhaitons également améliorer la façon dont ces propriétés personnalisées contextuelles héritent des valeurs. Actuellement, par exemple, si vous souhaitez ajuster la couleur de deux composants de séparateur, vous devez cibler ces deux composants spécifiquement avec des sélecteurs ou appliquer la propriété personnalisée directement sur l'élément avec l'attribut de style. Cela peut sembler acceptable, mais il serait plus utile que le développeur puisse définir ces styles sur un élément contenant ou même au niveau racine.


<nord-divider></nord-divider>

<section>
  <nord-divider></nord-divider>
   <!-- ... -->
</section>

<style>
  nord-divider {
    --n-divider-color: var(--n-color-status-danger);
  }

  section {
    padding: var(--n-space-s);
    background: var(--n-color-surface-raised);
  }
  
  section nord-divider {
    --n-divider-color: var(--n-color-status-success);
  }
</style>
Deux instances de notre composant de séparateur qui nécessitent deux traitements de couleur différents. L'un est imbriqué dans une section que nous pouvons utiliser pour un sélecteur plus spécifique, mais nous devons cibler spécifiquement la ligne de séparation.

Vous devez définir la valeur de la propriété personnalisée directement sur le composant, car nous les définissons sur le même élément via le sélecteur d'hôte du composant. Les jetons de conception globaux que nous utilisons directement dans le composant sont transmis directement, sans être affectés par ce problème, et peuvent même être interceptés sur les éléments parents. Comment tirer le meilleur parti de l'association de ces deux approches ?

Propriétés personnalisées privées et publiques

Les propriétés personnalisées privées ont été créées par Lea Verou. Il s'agit d'une propriété personnalisée "privée" contextuelle sur le composant lui-même, mais définie sur une propriété personnalisée "publique" avec un remplacement.



:host {
  --_n-divider-color: var(--n-divider-color, var(--n-color-border));
  --_n-divider-size: var(--n-divider-size, 1px);
}

.n-divider {
  border-block-start: solid var(--_n-divider-size) var(--_n-divider-color);
  /* ... */
}
CSS du composant Web de séparateur avec les propriétés personnalisées contextuelles ajustées de sorte que le CSS interne s'appuie sur une propriété personnalisée privée, qui a été définie sur une propriété personnalisée publique avec un remplacement.

En définissant nos propriétés personnalisées contextuelles de cette manière, nous pouvons toujours effectuer toutes les opérations que nous effectuions auparavant, comme hériter des valeurs de jeton globales et réutiliser des valeurs dans le code de notre composant. Le composant héritera également de manière fluide des nouvelles définitions de cette propriété sur lui-même ou sur n'importe quel élément parent.


<nord-divider></nord-divider>

<section>
  <nord-divider></nord-divider>
   <!-- ... -->
</section>

<style>
  nord-divider {
    --n-divider-color: var(--n-color-status-danger);
  }

  section {
    padding: var(--n-space-s);
    background: var(--n-color-surface-raised);
    --n-divider-color: var(--n-color-status-success);
  }
</style>
Les deux séparateurs à nouveau, mais cette fois, le séparateur peut être recoloré en ajoutant sa propriété personnalisée contextuelle au sélecteur de section. Le séparateur l'héritera, ce qui produira un code plus clair et plus flexible.

On peut affirmer que cette méthode n'est pas vraiment "privée", mais nous pensons qu'elle constitue une solution plutôt élégante à un problème qui nous préoccupait. Lorsque nous en aurons l'occasion, nous allons résoudre ce problème dans nos composants afin que notre équipe de développement puisse mieux contrôler l'utilisation des composants tout en bénéficiant des garde-fous que nous avons mis en place.

J'espère que cet aperçu de la façon dont nous utilisons les Web Components avec les propriétés CSS personnalisées vous a été utile. N'hésitez pas à nous faire part de vos commentaires. Si vous décidez d'utiliser l'une de ces méthodes dans votre propre travail, vous pouvez me retrouver sur Twitter @DavidDarnes. Vous pouvez également retrouver Nordhealth sur Twitter : @NordhealthHQ, ainsi que le reste de mon équipe, qui a travaillé dur pour rassembler ce système de conception et implémenter les fonctionnalités mentionnées dans cet article : @Viljamis, @WickyNilliams et @eric_habich.

Image principale par Dan Cristian Pădureț