AXA France

Canopée

Le Design System AXA France

Un socle commun pour trois univers applicatifs — Distributeur, Prospect et Client. Architecture, workflows, outils IA et contribution.

Distributeur

Prospect

Client

Présentation interne
github.com/AxaFrance/design-system

02Sommaire

Ce que nous allons voir

01

Le principe des thèmes

Trois univers, un socle commun

02

La structuration du projet

Monorepo, packages, apps Storybook

03

Les workflows

Dev, build, CI/CD, commits

04

Skills & plugins IA

Copilot, Claude, MCP Zeroheight, gh-aw

05

Ajouter un thème & contribuer

Process, conventions, ressources

+

Ressources & conclusion

Liens, Storybook, ZeroHeight, Figma

02 / 29

CHAPITRE 01

Le principe
des thèmes

Pourquoi un seul design system pour trois univers applicatifs différents ?

04Vision

Qu'est-ce que Canopée ?

Un point d'entrée unique pour utiliser le design system AXA France, qui unifie trois design systems historiques auparavant séparés.

Avant

3 libs indépendantes : react-toolkit (Slash), Apollo, Look&Feel
Conventions et API divergentes
Maintenance dupliquée

Aujourd'hui

Un monorepo npm workspaces
Packages unifiés @axa-fr/canopee-react / -css
Une API commune, des entry points par thème

Migration

Guide de migration depuis @axa-fr/react-toolkit
Anciens packages miroirs en cours de retrait
Documentation ZeroHeight & Figma par univers

04 / 29

05Les 3 univers

Trois univers, trois publics

B2B

Distributeur

(ex-Slash)

Applications internes collaborateurs / distributeurs
@axa-fr/canopee-react/distributeur
Issu de react-toolkit, migré intégralement

B2C

Prospect

(ex-Apollo)

Applications exposées aux prospects — AXA.fr
@axa-fr/canopee-react/prospect
Code partagé avec Client via prospect-client

B2C

Client

(ex-Look & Feel)

Applications espace client
@axa-fr/canopee-react/client
Code partagé avec Prospect via prospect-client

Pour chaque univers : un package -react (composants) et un package -css (styles), publiés séparément.

05 / 29

06Architecture

Code partagé, surcharges par thème

Prospect et Client partagent la même API : la logique vit dans *Common, chaque thème ne surcharge que le visuel.

Button/
  ButtonCommon.tsx  // logique partagée
  ButtonApollo.tsx  // surcharge Prospect
  ButtonLF.tsx     // surcharge Client

Règle d'or

Les composants ont exactement la même API, seul l'import change
Les fichiers thème (Apollo/LF) injectent CSS et sous-composants spécifiques
100 % de la logique métier reste dans le fichier Common

06 / 29

07Decision Record 0003

Pourquoi ce choix d'architecture ?

Décision actée le 14/01/2025 : un package par thème, avec un dossier common pour le code partagé.

Avantages

La majorité du code est commun aux deux thèmes
Seules les variantes spécifiques sont développées dans leur thème
Changements visuels mineurs isolés dans le package CSS

Inconvénients assumés

Davantage de pipelines à maintenir
Build légèrement plus complexe
Compensé par Turborepo pour l'orchestration

Décisions documentées dans docs/decision-records/ — format ADR, en anglais.

07 / 29

08En pratique

Une API, un import par thème

// Distributeur
import { Button } from
"@axa-fr/canopee-react/distributeur";

// Prospect
import { Button } from
"@axa-fr/canopee-react/prospect";

// Client
import { Button } from
"@axa-fr/canopee-react/client";

CSS seul

Pour une intégration HTML pure, sans React :

@import "@axa-fr/canopee-css/distributeur/Button/Button.css";
@import "@axa-fr/canopee-css/prospect/common/tokens.css";

Les tokens CSS (couleurs, espacements) sont importés une fois par application, par univers.

08 / 29

CHAPITRE 02

Structuration
du projet

Un monorepo npm workspaces orchestré par Turborepo.

10Monorepo

Vue d'ensemble du dépôt

Dossier	Contenu
packages/	canopee-react, canopee-css, eslint-config, prettier-config, stylelint-config
apps/	Storybooks : apollo-stories, look-and-feel-stories, slash-stories
plugins/	Plugins Copilot/Claude : canopee-distributeur, canopee-prospect-client
docs/	decision-records, guidelines, changelogs, workshops
samples/	Exemple d'intégration Vite
.github/	Workflows CI/CD + GitHub Agentic Workflows

Workspaces npm : samples/vite, apps/*, packages/* — npm 11.6.4, Node 24.11.1 (Volta).

10 / 29

11packages/canopee-react & -css

Là où vit le vrai code

packages/canopee-react/src/
├── distributeur/  // composants B2B
├── prospect-client/ // partagés B2C
│    └── Button/
│        ├── ButtonCommon.tsx
│        ├── ButtonApollo.tsx
│        └── ButtonLF.tsx
├── distributeur.ts   // entry point + CSS
├── prospect.ts
└── client.ts

Même logique côté CSS

packages/canopee-css/src/distributeur
packages/canopee-css/src/prospect-client
Tokens CSS centralisés par univers (common/tokens.css)
PostCSS configuré via packages/postcss-config
ESLint / Prettier / Stylelint mutualisés dans leurs packages dédiés

11 / 29

12Definition of Done

Code source multithème, stories & MDX à part

# packages/canopee-react/src/prospect-client/
Button/
├── ButtonCommon.tsx — logique partagée
├── ButtonApollo.tsx — surcharge Prospect
├── ButtonLF.tsx — surcharge Client
└── __tests__/Button.test.tsx

# apps/apollo-stories/src/components/
Button/
├── Button.stories.tsx
└── Button.mdx

# idem dans slash-stories / look-and-feel-stories

Checklist qualité

Multithème : fichier *Common partagé, surcharges *Apollo/*LF par thème si besoin
Tests : co-localisés dans packages/, avec testing-library + user-event
Documentation : stories + MDX vivent dans apps/{theme}-stories/, pas dans packages/
Accessibilité et responsive testés systématiquement
Dépréciation : tag @deprecated + mention dans le MDX
Copilot : mise à jour du skill associé dans plugins/

12 / 29

13Accessibilité

L'accessibilité, une exigence native

Standards visés

RGAA 4.0 (référentiel français) et WCAG 2.1/2.2 niveau AA
HTML sémantique natif avant tout recours à ARIA
Navigation clavier, focus visible et lecteurs d'écran testés

Outillage & process

jest-axe intégré aux tests unitaires : expect(await axe(container)).toHaveNoViolations()
Case Accessibilité obligatoire dans la Definition of Done de chaque composant
Agent Copilot dédié accessibility-expert pour la revue WCAG/RGAA

13 / 29

14apps/ — Storybook

Un Storybook par univers

Univers	App Storybook	Documentation
Distributeur	`apps/slash-stories`	Storybook · ZeroHeight · Figma (DS Slash V3)
Prospect	`apps/apollo-stories`	Storybook · ZeroHeight · Figma (Design System B2C)
Client	`apps/look-and-feel-stories`	Storybook · ZeroHeight · Figma (Design System B2C)

Chaque package publie deux tags npm : latest et next, avec leur propre Storybook déployé sur GitHub Pages.

14 / 29

CHAPITRE 03

Les workflows

Démarrer, builder, versionner, publier — et valider la qualité à chaque étape.

16Démarrer

Lancer le projet en local

Commande	Effet
`npm run dev`	Lance tous les Storybooks (build CSS + React en parallèle)
`npm run dev:distributeur`	Démarre uniquement l'univers Distributeur (slash-stories)
`npm run dev:prospect`	Démarre uniquement l'univers Prospect (apollo-stories)
`npm run dev:client`	Démarre uniquement l'univers Client (look-and-feel-stories)
`npm run build` / `build:*`	Build complet ou ciblé par univers
`npm test`	Exécute les tests Vitest sur tout le monorepo

16 / 29

17Turborepo & CI

Orchestration des builds et intégration continue

Turborepo

Orchestre les dépendances entre tâches (^build, ^lint)
Cache activé, sauf pour les tâches dev (persistantes)
npm run build = turbo build --concurrency=1

CI — `main.yml`

Build des packages + npm test
Scan qualité SonarCloud (code smells, couverture, sécurité)
CommitLint sur chaque pull request

17 / 29

18Sécurité

Qualité et sécurité du code

SonarCloud

Analyse à chaque pull request : Security Rating, code smells, bugs
Suivi de la couverture de tests et de la dette technique
Badges de qualité publics dans le README.md

Dépendances & conventions

Dependabot : mises à jour quotidiennes des dépendances npm, groupées par type
Secrets jamais committés dans le code source
CommitLint et revue de code obligatoires avant fusion

18 / 29

19Publication

Publier les packages — `publish.yml`

Déclenchement

À chaque push sur main, ou manuellement
Versionnage automatique via GitVersion (SemVer)
Distinction release stable / pré-release

Résultat

Publication npm des packages canopee-react / canopee-css
Tags latest (stable) et next (pré-release)
Permissions minimales : contents: write, id-token: write

19 / 29

20Conventional Commits

Des commits qui pilotent les releases

feat(canopee): ajout d'un composant xxx

fix(prospect,client): correction styles

feat(prospect)!: suppression d'une prop

BREAKING CHANGE: ...

Scopes disponibles

canopeeprospectclientdistributeurdesign-system

Anciens scopes slash, apollo, look&feel dépréciés mais tolérés
! + section BREAKING CHANGE pour les changements majeurs
Scopes deps, deps-dev, release réservés

20 / 29

CHAPITRE 04

Skills & plugins IA

Rendre Copilot et Claude naturellement experts du design system Canopée.

22Pourquoi

Pourquoi des plugins Copilot & Claude ?

Le design system peut être ajouté comme plugin GitHub Copilot : vos agents utilisent les composants AXA plus vite, et surtout bien mieux.

Rapidité

Moins d'aller-retours, moins d'erreurs de prop ou de composant inventé.

Fidélité

Les agents respectent strictement l'API documentée dans ZeroHeight.

Adoption

Les composants AXA sont utilisés plus naturellement et plus souvent.

Marketplace du chat, ou ajout manuel depuis plugins/canopee-distributeur et plugins/canopee-prospect-client.

22 / 29

23Catalogue des skills

Deux skills, un catalogue de composants

Plugin	Univers couverts	Contenu
`canopee-distributeur`	Distributeur (B2B)	SKILL.md + ~30 fichiers de référence (Button, Table, Steps, Select…)
`canopee-prospect-client`	Prospect & Client (B2C)	SKILL.md + 18 fichiers de référence par famille de composants

Chaque SKILL.md décrit : les règles toujours appliquées (BEM, props HTML natives, pas de leaked render), le catalogue de composants avec leur fichier de référence, et le workflow documentaire obligatoire.

23 / 29

24Outillage IA avancé

MCP Zeroheight & GitHub Agentic Workflows

MCP Zeroheight

Deux serveurs MCP configurés dans .vscode/mcp.json
Un par couple d'univers : Client+Prospect / Distributeur
Workflow obligatoire : search-pages → get-page avant toute génération de code UI

GitHub Agentic Workflows (gh-aw)

Automatisations IA décrites en Markdown + frontmatter YAML
gh aw compile génère les .lock.yml exécutables
Job agent en lecture seule, écritures via safe-outputs
Guide complet : docs/guidelines/agentic-workflows.md

24 / 29

CHAPITRE 05

Ajouter un thème
& contribuer

Faire évoluer Canopée — en équipe, avec les bonnes conventions.

26Nouveau thème

Comment ajouter un nouveau thème ?

1
Documenter la décision
Rédiger un decision-record (docs/decision-records/) décrivant le besoin et l'architecture retenue.
2
Créer les dossiers composants
Nouveau sous-dossier dans canopee-react/src et canopee-css/src, avec *Common si du code peut être partagé.
3
Définir les tokens CSS
Un fichier tokens.css dédié (couleurs, espacements, typographies) pour le nouveau thème.
4
Ajouter un entry point
Nouveau fichier nom-theme.ts à la racine du package, avec ses imports CSS.
5
Créer l'app Storybook
Nouvelle app dans apps/, scripts dev:theme / build:theme ajoutés au package.json racine.
6
Outiller l'IA
Créer le plugin/skill associé dans plugins/ et le serveur MCP ZeroHeight correspondant.

26 / 29

27Contribuer

Comment contribuer ?

# 1. Fork puis clone
git clone .../votre-compte/design-system

# 2. Nouvelle branche
git switch -c nom-de-ma-branche

# 3. Développer + tester
npm run start

# 4. Ouvrir une Pull Request

Bon à savoir

Tâches et discussions suivies via les issues GitHub
Commits au format Conventional Commits, scope obligatoire
Respect du CODE_OF_CONDUCT.md
CI (build, tests, SonarCloud, CommitLint) doit passer au vert

27 / 29

28Ressources

Ressources clés

Documentation

Storybook — Distributeur · Prospect · Client
ZeroHeight — Distributeur · Prospect / Client
Figma — Distributeur · Prospect / Client

Process

CONTRIBUTING.md
docs/decision-records/
docs/guidelines/ (CSS, props, a11y, Copilot)

Suivi

Installer les packages npm

npm @axa-fr/canopee-react
npm @axa-fr/canopee-css

28 / 29

Merci

Contribuons
à Canopée

Des questions ? Une idée de composant manquant ? Ouvrez une issue ou une pull request sur le dépôt.

github.com/AxaFrance/design-system

29 / 29

Ce que nous allons voir

Qu'est-ce que Canopée ?

Avant

Aujourd'hui

Migration

Trois univers, trois publics

Distributeur

Prospect

Client

Code partagé, surcharges par thème

Règle d'or

Pourquoi ce choix d'architecture ?

Avantages

Inconvénients assumés

Une API, un import par thème

CSS seul

Vue d'ensemble du dépôt

Là où vit le vrai code

Même logique côté CSS

Code source multithème, stories & MDX à part

Checklist qualité

L'accessibilité, une exigence native

Standards visés

Outillage & process

Un Storybook par univers

Lancer le projet en local

Orchestration des builds et intégration continue

Turborepo

CI — main.yml

Qualité et sécurité du code

SonarCloud

Dépendances & conventions

Publier les packages — publish.yml

Déclenchement

Résultat

Des commits qui pilotent les releases

Scopes disponibles

Pourquoi des plugins Copilot & Claude ?

Rapidité

Fidélité

Adoption

Deux skills, un catalogue de composants

MCP Zeroheight & GitHub Agentic Workflows

MCP Zeroheight

GitHub Agentic Workflows (gh-aw)

Comment ajouter un nouveau thème ?

Comment contribuer ?

Bon à savoir

Ressources clés

Documentation

Process

Suivi

Installer les packages npm

CI — `main.yml`

Publier les packages — `publish.yml`