Kalka
Documentation

Composants et variables

Des composants réutilisables avec variantes et propriétés, la page Variables avec ses collections et ses modes, et comment les variables deviennent des propriétés personnalisées CSS et des design tokens.

docs / components-variables

Composants

Un composant est un design que vous réutilisez : un bouton, une carte, une barre de navigation. Ses copies, appelées instances, le suivent. Modifiez le composant et toutes les instances changent, sauf ce qu’une instance remplace.

  • Créer un composant : sélectionnez des calques et appuyez sur Cmd Alt K (Ctrl Alt K).
  • Créer une instance : faites glisser le composant depuis le panneau Ressources sur le canvas, ou utilisez Insérer une instance dans ce panneau.
  • Aller au composant principal passe d’une instance à son composant.
  • Détacher l’instance (Cmd Alt B, Ctrl Alt B) refait d’une instance de simples calques.

Le panneau Ressources liste les composants du document, en grille ou en liste, avec une recherche.

Variantes

Les variantes sont des versions d’un même composant, comme un bouton principal ou secondaire, petit ou grand. Sélectionnez plusieurs composants et utilisez Créer un jeu de composants (Shift Cmd K, Ctrl Shift K), puis ajoutez des propriétés de variante et leurs valeurs. Chaque variante doit avoir sa propre combinaison de valeurs. Sur une instance, vous changez de variante depuis le panneau Design.

Propriétés de composant

En plus des variantes, un composant peut exposer :

  • des propriétés Texte, pour changer un libellé sur chaque instance ;
  • des propriétés Booléen, pour afficher ou masquer une partie ;
  • des propriétés Permutation d’instance, pour remplacer un composant imbriqué, comme une icône ;
  • des slots, des zones où chaque instance reçoit ses propres calques, avec une limite de nombre.

Créez-en une avec Créer une propriété… dans le panneau Design, ou depuis un champ avec Appliquer une propriété de composant. Les instances affichent ces propriétés en haut du panneau Design.

Comportements

Un composant peut se comporter comme un vrai contrôle : un interrupteur, une case à cocher, un curseur, des onglets, un champ de texte, un accordéon, un bouton avec ses états survol, appuyé, focus et désactivé, et d’autres. Choisissez-le dans la section Comportement du composant. Affichage › Aperçu (Cmd Alt Enter) fait alors vraiment fonctionner les contrôles : vous pouvez taper dans un champ de texte, faire glisser un curseur, ouvrir un accordéon, au clavier aussi. Rien ne change dans le document pendant vos essais ; Esc ramène à l’édition.

Bibliothèques

Pour partager des composants entre documents, publiez un document comme bibliothèque avec Publier la bibliothèque, puis activez-la dans un autre document avec Gérer les bibliothèques. Quand la bibliothèque change, Examiner les mises à jour de la bibliothèque montre ce qui a changé, côte à côte ou en superposition, avant que vous mettiez à jour.

Variables

Les variables sont des valeurs nommées que vous réutilisez : une couleur de marque, un espacement, une taille de police, un libellé. Modifiez la variable et chaque calque qui l’utilise suit.

Ouvrir la page Variables

Cliquez sur Variables dans le rail de gauche. Dans l’éditeur desktop, la page Variables s’ouvre par-dessus les panneaux et le canvas. Cliquez à nouveau sur Variables, choisissez un autre panneau ou appuyez sur Esc pour retrouver le canvas tel qu’il était. Vous pouvez aussi l’ouvrir avec Affichage › Variables…, ou avec Ouvrir les variables dans le panneau Design quand rien n’est sélectionné. Sur un écran de téléphone, elle s’ouvre dans une boîte de dialogue.

La page Variables avec une collection Tokens : des variables de couleur, d’espacement et de rayon avec leurs valeurs Light et Dark, leurs noms CSS, et la feuille de style générée en dessous
La page Variables : chaque variable avec son nom CSS et une valeur par mode, et la feuille de style qu’écrit Kalka.

Types

Type Pour
Couleur remplissages, contours, couleurs d’ombre
Nombre tailles, espacements, rayons, opacité, tailles de police
Texte libellés, textes, familles de police
Booléen vrai ou faux, par exemple pour afficher un calque

Une variable peut être limitée à certains champs grâce à ses portées, pour qu’un espacement n’apparaisse jamais dans une liste de couleurs. Son expression CSS lui permet de contenir dans le code quelque chose comme clamp(1rem, 4vw, 1.5rem).

Collections et modes

Les variables vivent dans des collections, comme Couleurs ou Espacements, et peuvent être rangées en groupes. Une collection peut avoir des modes : clair et sombre, compact et confortable, un par marque. Chaque variable a une valeur par mode.

Chaque mode indique quand il s’applique dans le CSS exporté :

  • activé à la main, avec un attribut comme data-theme ;
  • quand le système est en mode sombre ou clair ;
  • avec le contraste élevé ou les animations réduites ;
  • en dessous ou au-dessus d’une largeur d’écran, ou d’une largeur de conteneur ;
  • ou sous n’importe quel sélecteur CSS ou requête @media, @supports ou @container que vous écrivez.

Utiliser une variable

À côté d’un champ, cliquez sur Utiliser une variable et choisissez-en une dans la petite liste ; survoler une variable de couleur ou de nombre en donne l’aperçu sur le canvas. Détacher la variable remet une valeur simple. À partir d’une valeur déjà réglée, Créer une variable de couleur ou Créer une variable numérique en fait une variable en une étape.

Les variables dans le code

Les variables sont des propriétés personnalisées CSS. Le mode par défaut de chaque collection est écrit dans :root, et les autres modes ne remplacent que les valeurs qui diffèrent, sous leur condition. Une variable nommée Gray/50 devient --color-gray-50, et Space/small devient --spacing-small ; vous pouvez choisir votre propre nom CSS.

Depuis la page Variables, vous pouvez :

  • Copier toutes les variables en CSS, ou en thème Tailwind (@theme) ;
  • Exporter en design tokens : un .zip de design tokens W3C, un fichier par mode de collection ;
  • Importer des design tokens depuis des fichiers .json, .tokens ou .zip. Les variables de même nom sont mises à jour ; rien n’est supprimé.

Dans un dossier Kalka, les variables sont enregistrées en design tokens W3C dans design-system/tokens.json, et en CSS dans design-system/tokens.css. Voir Fichiers et versions.