Design System du pass Culture

Ce repository contient le code nécessaire à la génération des design tokens du Design System du pass Culture. Si vous cherchez des informations plus générales à propos de ce design system, rendez-vous sur la documentation.

Si vous êtes développeur·euse ou designer·euse, et que vous voulez utiliser le Design System du pass Culture, vous pouvez commencer avec les kits de démarrage.

Installation et utilisation

La dernière version de la librairie peut être installée dans un projet avec la commande suivante :

yarn add https://github.com/pass-culture/design-system.git#[TAG_VERSION]

La librairie donne accès aux design tokens soit via un fichier de variables CSS qu'on peut importer cette manière :

@import 'design-system/build/pro/variables-light.css';

Dans ce cas, les variables CSS sont directement déclarées à la racine de l'arbre du document.

Ou bien via un fichier typescript depuis lequel on importe l'objet contenant les design tokens :

import * as tokens from 'design-system/dist/build/jeune/index.light.web.ts'

Création d'un nouveau tag

A chaque nouvelle version des design tokens, un nouveau tag est généré. La création du nouveau tag se fait de la manière suivante :

1. Créer une nouvelle branche depuis main avec le nom pc-[NUMERO_TICKET ou BSR]
2. Générer un nouveau build :

yarn build

3. Commit les changements et les poussez sur la branche

4. Créer une PR de la branche vers main

5. Une fois la PR approuvée et mergée, basculer sur main et exécuter la commande suivante :

./scripts/generate_dist_case.sh

Il faudra peut-être installer jq si ce n'est pas déjà fait :

brew  install  jq

Il se peut qu'il faille modifier les permissions pour exécuter le script :

chmod  +x  ./scripts/generate_dist_case.sh

Fonctionnement du build

Le but du build est de transformer l'objet JSON contenant les design tokens exportés depuis Figma en des fichiers exploitables par les applications du pass Culture (les fichiers variables.light.web.css ou index.dark.web.ts donnés en exemple plus haut).

Transformation des design tokens

On utilise la librairie style-dictionary qui nous permet de configurer des pipelines qui appliquent des transformations spécifiques pour chaque environnement de destination.

Ces fichiers de configuration se trouvent dans src/configs et permettent de construire pour chaque brand les fichiers de variables déclinés pour chaque plateforme et pour chaque thème concernés.

Autres fichiers générés

On génère aussi deux autres fichiers :

• Le fichier font-faces.css contenant les définitions des typographies utilisées dans les design tokens
• Le fichier font-preloads.ts contenant la liste des preloads à injecter dans le HTML des applications pour que les glyphes des typographies soient téléchargés en premier

Structure des design tokens

Les design tokens sont séparés en trois catégories :

• Les global tokens, c'est à dire les valeurs par défaut des tokens
• Les tokens de thèmes qui surchargent les valeurs par défaut au moment du build
• Les brand tokens qui surchargent les tokens pour une brand et un thème donnés

Global tokens

Les global tokens sont organisés par groupe. On a par exmeple typography ou color. Chacun de ces groupes est divisé en plusieurs fichiers :

• Les primitive tokens qui font référence à des valeurs absolues (par ex: color-grey-0: "#fff")
• Les semantic tokens qui sont des abstractions des primitive tokens. Ils peuvent être lié à un style partagé par les applications (par ex: color-text-default), ou a un composant spécifique (par ex: button-color-background-default-hover)

Theme tokens

Les theme tokens sont regroupés dans des fichiers spécifiques pour chaque thème possible sur les différentes plateformes (tel que dark.json pour le thème sombre).

Brand tokens

Les brand tokens sont regroupés dans des fichiers spécifiques pour chaque plateforme et chaque thème possible (tel que pro-dark.json pour la surcharge du thème sombre sur l'application pro).

Comment ajouter une brand ?

• Ajouter à src/configs/brands une config de plateformes et de thèmes pour la nouvelle brand
• Ajouter un fichier de surcharge pour chaque thème dans src/tokens/brands sous la forme [BRAND]-[THEME].json

Comment ajouter un thème ?

• Ajouter le thème aux listes des thèmes dans les configs de brand concernées dans src/configs/brands
• Ajouter un fichier de surcharge pour chaque brand dans src/tokens/brands sous la forme [BRAND]-[THEME].json