---
title: Contribution
shortTitle: Contribution
description: Cette page décrit les règles à suivre pour contribuer au DSFR, depuis l’installation locale jusqu’aux bonnes pratiques de développement, de documentation et de tests.
shortDescription: Guide complet pour contribuer au DSFR
keywords: contribution, DSFR, git, pull request, installation, développement, tests, compilation, documentation, sassdoc, eslint, accessibilité, ejs
excerpt: Toutes les informations nécessaires pour installer, développer, tester et proposer des contributions au Système de Design de l’État.
summary: Cette page détaille les étapes pour contribuer efficacement au Système de Design de l’État - installation locale, structure des packages, usage de Sass, EJS et JavaScript, conventions Git, génération de la documentation et tests automatisés. Elle précise également les exigences légales et les outils disponibles pour garantir qualité, accessibilité et traçabilité du code. Un guide incontournable pour les contributeurs souhaitant enrichir ou corriger le DSFR.
order: 2
sort: order
---


# Contribution

Avant de commencer à utiliser le Système de Design de l’État (ci-après, DSFR) , veillez à prendre connaissance des [conditions générales d'utilisations](https://github.com/GouvernementFR/dsfr/blob/main/doc/legal/cgu.md). Si vous souhaitez contribuer au DSFR, veuillez prendre connaissance des documents relatifs à [la cession des droits d'auteur](https://gouvfr.atlassian.net/wiki/spaces/DB/pages/779681874/Contribuer+au+DSFR#Proposer-une-pull-request) et du [certificat garantissant l'originalité de votre contribution](https://gouvfr.atlassian.net/wiki/spaces/DB/pages/779681874/Contribuer+au+DSFR#Signature-des-commits).

## Installation

### Installation locale

Le DSFR est basé sur une architecture NodeJS, il est donc nécessaire d’installer une version récente de [nodeJs](https://nodejs.org/). Dans le terminal nous utiliserons les commandes de npm ou yarn pour lancer les scripts.

Le dépôt est disponible à cette adresse : [GitHub - GouvernementFR/dsfr: Système de Design de l’État](https://github.com/GouvernementFR/dsfr)

Afin de pouvoir commencer à développer et contribuer au DSFR, assurez-vous tout d'abord de faire un fork du projet depuis votre compte github (Fork a repo - GitHub Docs )

Il suffit ensuite de cloner votre fork, en téléchargeant les sources depuis le bouton “clone” de github, ou via un terminal avec commande : `git clone https://github.com/VOTRE_NOM_UTILISATEUR_GITHUB/dsfr`

La branche `**dev-X.X.X**` (X.X.X correspondant au numéro de version à venir) est la principale branche de travail - la branche main correspondant aux versions de productions livrées aux utilisateurs. Il est donc nécessaire de créer de nouvelles branches de travail pour l'ajout et la modification de packages depuis la branche dev. (Voir la section Utilisation > Git, pour le fonctionnement détaillé).

Une fois le projet récupéré, il est nécessaire d'installer les dépendances (node_modules) avec :

```html
yarn
```

OU

```html
npm i
```

OU

Enfin, il est nécessaire de lancer un serveur local pour visualiser les pages d’exemples :

```html
yarn serve
```

OU

```html
npm run serve
```

Un serveur local sera alors lancé sur l'adresse `localhost:8080`. Accéder à `http://localhost:8080/example/` pour voir la liste des exemples.

### Packages

Le DSFR est un monorepo proposant différents composants, listés dans le dossier `src/component`.

Un composant doit avoir une arborescence de type :

```html
/
└── example/
└── style/
└── template/
    ├── ejs/
└── index.scss
└── main.scss
└── legacy.scss
└── .package.yml
```

- Le dossier `/example` comprend les fichiers ejs d’exemple (ils utilisent les templates du composant en passant des valeurs d’exemple en paramètre).
- Le dossier `/styles` contient les fichiers .scss permettant la génération du css du composant.
- Le dossier `/templates` contient les templates des composants (la mise en forme html).

Certains de ces packages sont dépendants les uns des autres. Chacun de ces packages possède donc un fichier `package.yml`, listant l'ensemble de ses dépendances à d'autres composants du DSFR.

Celui-ci gère les imports et le wrapper des examples html générés ainsi que l'implémentation des `readme.md`. Il est structuré de cette façon :

```html
id: buttons (nom du package)
title: Boutons (nom du composant, en français)
description: description insérée dans le readme
doc: lien vers la documentation
wrapper: col-8 (le conteneur dans lequel on insert l'example)
styles: (liste des packages dont le css dépend)
  - core
scripts: (liste des packages dont le js dépend)
  - core
follow:   (pas de dépendance à link mais doit etre placé après link)
  styles:
    - links
example: (dépendances sur la page d'exemple uniquement)
  styles:
    - header
```

## Utilisation

### Sass

Le DSFR utilise Sass pour la génération automatique des styles liés à chaque composant. Chacun d'entre eux possède une structure identique à ce niveau, par exemple le composant `button` :

```html
/src/component/button
└── styles
    ├── _module.scss
    ├── _scheme.scss
    ├── _legacy.scss
    ├── _tool.scss
    ├── _setting.scss
    └── module/
        └── _buttons-group.scss
└── index.scss
└── main.scss
└── legacy.scss
```

Il peut donc y avoir plusieurs fichier .scss, mais seuls `main.scss` à la racine du composant, et `_module.scss` sont obligatoires, et chacun à son propre rôle :

- `main.scss` : Fichier principal du composant servant d'entrée, et composé uniquement d'@import. Il importe le fichier index ainsi que des fichiers modules du composant (obligatoire)
- `index.scss` : Fichier secondaire du composant, aussi composé d'@imports, importe uniquement les fichiers de settings et tools du composant ainsi que l'index.scss des composants dépendants. (obligatoire)
- `_module.scss` : Comprend l'ensemble des styles du module (obligatoire)
- `_scheme.scss` : doit contenir tous les styles liés aux couleurs, afin de gérer la thématisation. (optionnel)
- `legacy.scss` : Permet de générer un fichier séparé pour le support navigateur (facultatif)
- `_legacy.scss` : Contient tous les styles uniquement lié au support des anciens navigateurs (facultatif)
- `_setting.scss` : Contient les variables sass utilisées par le composant (optionnel)
- `_tool.scss` : Contient les functions et mixins pouvant être utilisés par le composant, par exemple la gestion des token d'espacements (optionnel)
- `modules/_buttons-group.scss` : Example de sous-composant permettant d'alléger `_module.scss`, qui importe ce fichier

### Javascript

Certains packages font utilisation de javascript, afin d'apporter une couche interactive à ceux-ci. C'est le cas par exemple du package navigation, où le javascript est utilisé pour déplier les sous-menus. La couche javascript est structurée comme ceci, par exemple pour le composant `navigation` :

```html
/src/component/navigation
└── script
    └── navigation/
        ├── navigation-item.js
        ├── navigation.js
        ...
└── api.js
└── index.js
└── main.js
```

`api.js` : importe depuis core l'objet global qui contient les classes, variables et instances du DSFR (Fichier identique dans chaque package avec du js).

`index.js` : Ajoute à l'objet global `api` des définitions de classes et variables spécifiques au composant.

`main.js` : importe l'index et permet l'initialisation du composant.

Un Dossier `script` qui contient un dossier par fonctionalité js, ici `navigation` puis :

`navigation.js` (ou nom-classe.js) contient le code de la fonctionnalité js, structurée en classes instanciables (es6).

Lors du `yarn release`, le javascript est compilé en version "module" (es6) et "nomodule" (es5), ainsi qu'en version .min et .map. En mode développement, `yarn build` permet de regénérer uniquement la version .module.js (es6 non minifié)

### EJS

Nous utilisons au sein du DSFR, le langage de template EJS ([documentation officielle](https://ejs.co/#docs)), permettant la génération des pages d'exemples au format HTML, ainsi que les snippets de code de manière automatisée.

Les fichiers ejs sont séparés dans 2 dossiers, par exemple pour le package `callout` :

```html
/src/component/callouts
└── example
    ├── index.ejs
    └── samples/
        └── callout-default.ejs
└── template
    └── ejs
        └── callout.ejs
```

Dans le dossier `example`, `ìndex.ejs` est la page d'exemple publiée, elle affiche les différents exemples grâce à la fonction `sample()` (qui inclut l'exemple et le snippet de code) Le dossier `sample` contient les différents exemples (inclusion des templates avec des données d'exemples)

Dans le dossier `templates`, on insère ici les templates dans un sous-dossier nommé en fonction du système de templating utilisé (`ejs` pour l'instant). Ces templates sont paramétrables pour y injecter des données. Chaque fichier possède une documentation sommaire détaillant ces paramètres.

Pour accéder aux fonctions du core (comme `includeClasses()` et `includeAttr()`), chaque template inclut l'`index.ejs` de core au début du fichier : `<% eval(include('../../../core/index.ejs')); %>`

Afin de générer tous les exemples HTML utilisez `yarn release`. Ou, plus spécifiquement avec `yarn build`, le paramètre `-h` de yarn build permet de reconstruire uniquement l'html : `yarn build -h [-p nomPackage]`, avec `-p` pour préciser le(s) package(s).

### Git

#### Branches

Afin de travailler sur un nouveau package, ou un correctif d'un package existant, il est nécessaire de créer une nouvelle branche à partir de la branche `dev`. `git checkout -b prefixe/ma-branche dev`

#### Nommage des branches

Afin d'organiser et d'identifier rapidement la nature du contenu des branches, il est nécessaire de préfixer les branches : feat/nom-de-la-branche pour les nouvelles fonctionnalités ou nouveaux composants. fix/nom-de-la-branche pour les correctifs apportés sur des fonctionnalités ou composants existants.

#### Commits

Nous utilisons des [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) qui doivent donc s'écrire sous la forme suivante :

```html
<type>[optional scope]: <description en français>

[optional body]

[optional footer(s)]
```

Les valeurs possibles pour le `type` de commit sont :

- **fix** : un commit de type fix permet de corriger un bug ([[PATCH]](https://semver.org/#summary)).
- **feat** : un commit de type feat permet d'introduire une nouvelle fonctionnalité ([[MINOR]](https://semver.org/#summary)).
- D'autres types que feat et fix peuvent être utilisés, nous utilisons [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional), qui recommande l'utilisation des principaux types suivants : build, chore, ci, docs, style, refactor, perf, test.
- **BREAKING CHANGE** : un commit avec un footer BREAKING CHANGE introduit un changement important dans le code ([[MAJOR]](https://semver.org/#summary)).

Les messages de commits sont écrits en français (exception faite des mots réservés par conventional commit, ainsi que les termes techniques).

Exemple de commit simple :

```html
feat: ajout du composant Alerte
```

Exemple de commit avec `scope` le nom du composant ou de la f, description et `BREAKING CHANGE` footer

```html
fix(core): maj mixin: ancien-nom devient nouveau-nom

BREAKING CHANGE: nouveau nom pour la mixin ....
```

#### Signature des commits

Afin de garantir l'originalité des contributions, nous demandons aux contributeurs de signer leurs commits et/ou de nous faire parvenir le [certificat de garantie de l'origine du développeur](https://github.com/GouvernementFR/dsfr/blob/main/doc/legal/cgod.md) signé.

Pour signer un commit :

```html
git commit --signoff (ou git commit -s)
```

#### Proposer une pull request

> [!IMPORTANT]
> Avant de proposer une pull request , assurez vous que vous respectez [la garantie d’origine de vos développements](https://github.com/GouvernementFR/dsfr/blob/main/doc/legal/cgod.md), et pour les personnes n'étant pas des agents de l’État, que vous avez pris connaissance des documents relatifs à [la cession des droits d’auteur](https://github.com/GouvernementFR/dsfr/blob/main/doc/legal/cession.md), document à nous transmettre signé.Toute ‘pull request’ ne respectant pas ces pré-requis sera systématiquement rejetée.

Pour contribuer sur le git DSFR, il convient d’utiliser une “pull request” (PR). Lorsque vous estimez que votre développement est terminé et qu'il peut-être révisé par l'équipe DSFR, vos devez créer une pull request depuis github ([Pull requests · GouvernementFR/dsfr](https://github.com/GouvernementFR/dsfr/pulls) ) ou github cli (gh). La pull request suit les même règles de nommage décrites précédemment (branches, commits), à savoir le [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Une description détaillant le problème à résoudre, la façon dont la contribution résout le problème et toute autre information utile à la revue de code est fortement conseillée !

La pull request doit être faite depuis la branche de votre fork vers **la branche dev-X.X.X** du dépôt officiel.

## Compilation

La compilation des sources permet de créer un dossier `dist`, `exemple` et `.config` à la racine du projet. Le dossier `dist` contient les fichiers CSS et JS compilés, ainsi que les favicons et l'ensemble des fontes utilisées au sein du DSFR.

Le dossier `.config` contient les variables générales JS et SCSS ainsi que la configuration nécessaire au build. Plus particulièrement le fichier `config.json` répertorie toute l’arborescence de `src`, les dépendances et leur ordre qu’il récupère depuis les fichiers `package.yml` de chaque package et `folder.yml` pour les dossier (src, component, page, pattern)

Le dossier `example` contient les exemples HTML générés depuis les samples ejs. L'ordre des imports css et js est défini par l'ordre des dépendances dans le `package.yml`

La commande générale pour lancer la génération des fichiers dist, des exemples, ainsi que les tests est :

```html
yarn release
```

En mode développement, il est possible d'utiliser la commande :

```html
yarn build
```

Cette commande permet de générer uniquement les fichiers css/js/html. Cette commande est plus rapide puisqu'elle n’exécute pas les test, et ne compile pas les fichier .map, .md, .min.css, .nomodule.js...

De plus, grâce au paramètre `-p` il est possible de spécifier uniquement les packages que l'on souhaite recompiler.

Pour voir les différents paramètres disponibles : `yarn build --help`

## Autres commandes

### Icônes

La gestion des icônes se fait à l'aide d'une webfont, chargée directement via CSS en base64. Celle-ci est générée automatiquement à partir des fichiers `.svg` se trouvant dans le dossier `src/core/icon/svg/`. Il est donc possible d'ajouter des icônes, en ajoutant des fichiers `.svg` à ce dossier, et en relançant le build

```html
yarn build --clean
```

### Sassdoc

Des commentaires spéciaux sont utilisés sur l'ensemble des fichier scss, afin de permettre la génération d'une [Sassdoc](http://sassdoc.com/) automatiquement, documentant l'ensemble des mixins et functions utilisés sur le DSFR :

```html
yarn styleguide
```

Cette commande permet la génération de la doc dans le dossier `sassdoc`, à la racine du projet.

### Tests

Afin de s'assurer de la qualité du code, nous utilisons des tests automatisés qu'il est nécessaire d'exécuter régulièrement pour vérifier que le code du DSFR reste valide et cohérent, notamment avant d'effectuer des pull requests sur le dépôt de production, et avant publication sur NPM.

Ces tests sont exécutés lors de la commande : `yarn release`, ou plus spécifiquement avec :

Qui peut être combiner avec `-p nomPackage` pour spécifier un ou des package(s).

Pour voir les différents paramètres disponibles : `yarn build --help`

### Tests Sass

Afin de tester les différentes functions et mixins, nous utilisons jest et sass-true, afin d'effectuer une batterie de tests, présents dans un fichier `tests/_sass-tests.scss` au sein de certains packages.

Ces tests permettent de vérifier que le code renvoyé par ces derniers est bien conforme. (Par exemple, vérifier que la mixin de line-height renvoie bien la bonne valeur). Ces tests sont effectués lors du yarn release, ou plus spécifiquement avec :

```html
yarn build --test
```

### Tests d'accessibilité

Pour tester de manière automatisée l'accessibilité des composants du DSFR, nous utilisons [Pa11y](https://pa11y.org/) sur les pages de tests des différents packages. Ces tests sont effectués lors du "yarn release", ou plus spécifiquement avec :

```html
yarn build --test
```

Afin d'exclure un élément à tester au niveau des pages de test, il est possible de lui attribuer une classe spécifique `.is-pa11y-hidden` Les tests se jouent automatiquement sur chaque page de test de package, en mode normal puis en Darkmode

### Lint

Pour vérifier de manière automatisée les erreurs de syntaxe, de mise en forme du code, ou de non respect des bonne pratiques, nous utilisons esLint lors du `yarn release` ou plus spécifiquement avec :

```html
yarn build --test
```

La configuration est présente dans le fichier .eslintrc.json. Elle reprend en grande partie la configuration standard de esLint.
