MBA Design System

Design System pour l'écosystème Ma Boussole Aidant.

Pour les LLM / AI Assistants

Si vous êtes un assistant IA (Claude, Cursor, Copilot, Codex, etc.) qui édite du code consommant ce Design System, lisez d'abord AGENTS.md. Il décrit l'architecture en couches, la règle d'or pour Tailwind v4, et la table de référence complète des tokens.

Règle d'or, en une phrase : utilisez toujours les classes utilitaires générées par le preset Tailwind (text-primary-900, p-md, rounded-md, shadow-md) — n'écrivez jamais [var(--mba-...)] en valeur arbitraire, le preset existe précisément pour éviter ce contournement.

Activation dans une app consommatrice

Les outils IA (Claude Code, Cursor, Codex…) lisent AGENTS.md / CLAUDE.md à la racine du repo courant, pas dans node_modules/. Pour activer les instructions de ce DS dans une app cliente, copiez ce bloc dans le CLAUDE.md (ou AGENTS.md) à la racine de votre app :

## Design System : @maboussoleaidant/design-system

Cette app consomme `@maboussoleaidant/design-system`. Avant d'écrire du HTML/template avec des classes Tailwind ou MBA, lis les instructions complètes :

📄 `node_modules/@maboussoleaidant/design-system/AGENTS.md`

**Règle d'or** : utilise les utilitaires Tailwind générés par le preset (`text-primary-900`, `p-md`, `rounded-md`, `shadow-md`, `font-heading`), **jamais** `class="*-[var(--mba-...)]"`. Le preset existe pour éviter ce contournement.

Le fichier AGENTS.md est inclus dans le tarball npm — il sera disponible dès npm install.

Installation

npm install @maboussoleaidant/design-system

Usage

Option 1 : Composants MBA uniquement (sans Tailwind)

Pour les sites WordPress ou vitrines qui n'ont besoin que des composants .mba-* :

<link rel="stylesheet" href="https://unpkg.com/@maboussoleaidant/design-system/dist/mba-design-system.min.css">

Ou en import CSS :

@import "@maboussoleaidant/design-system";

Option 2 : Avec Tailwind v4 (recommandé pour les apps)

Pour les applications Angular/React/Astro qui utilisent Tailwind v4, importez le preset pour avoir accès à toutes les classes Tailwind JIT avec les tokens MBA :

/* styles.css */
@import "@maboussoleaidant/design-system";
@import "tailwindcss";
@import "@maboussoleaidant/design-system/preset";

Cela vous donne accès à :

• Toutes les classes Tailwind générées par le JIT (h-screen, animate-spin, etc.)
• Les tokens MBA mappés : bg-primary-500, p-sm, rounded-xs, shadow-md, etc.
• Les composants .mba-* du Design System

Note : Le fichier mba-tailwind.css est pré-compilé pour le Storybook uniquement. Utilisez le preset ci-dessus pour vos projets.

Option 3 : Tokens uniquement

Pour intégrer uniquement les variables CSS (couleurs, spacing, etc.) :

@import "@maboussoleaidant/design-system/tokens";

Assets

Le package inclut tous les assets nécessaires au bon fonctionnement des composants :

assets/
├── fonts/                      # Polices (Open Sans, Congenial, Material Symbols)
├── icons-social.svg            # Sprite SVG des icônes sociales
├── logo-mba-agirc-arrco.svg    # Logo standard
├── logo-mba-agirc-arrco-pro.svg # Logo version Pro
└── wave.svg                    # Décoration wave

Les fonts utilisent des chemins relatifs : les bundlers modernes (Vite, webpack 5) les résolvent automatiquement depuis node_modules. Aucune configuration supplémentaire nécessaire.

Développement

# Installer les dépendances
npm install

# Build
npm run build

# Watch mode
npm run dev

Ajouter un composant

Quand tu crées un nouveau src/components/_mon-composant.css :

1. Importer dans src/components/index.css :

   @import './_mon-composant.css';

2. Référencer dans AGENTS.md — ajouter une entrée dans COMPONENT_FILES au début de scripts/build-agents-md.mjs :

   { path: 'src/components/_mon-composant.css', label: 'Mon composant', prefixes: ['mba-mon-composant'] },

   Puis régénérer :

   npm run docs:agents

   Si tu oublies cette étape, npm run docs:agents plante avec un message clair, et npm publish est bloqué via prepublishOnly. C'est volontaire — ça force le composant à apparaître dans AGENTS.md pour que les LLM le découvrent.

3. Builder et créer la story Storybook comme d'habitude.

Publier une nouvelle version

Une fois ta PR mergée sur development (ou main) :

git checkout development
git pull
npm version patch        # ou minor / major selon la nature du changement
npm publish

Ce qui se passe sous le capot

npm publish déclenche prepublishOnly, qui exécute dans l'ordre :

1. npm run docs:agents:check — régénère AGENTS.md depuis le preset + les composants, puis git diff --exit-code AGENTS.md.
   • ✅ Aucun diff → on continue.
   • ❌ Diff → publish avorté. Lance npm run docs:agents, commit le résultat, push, retry.
2. npm run build — build standard (assets, CSS, tailwind, minification).
3. npm publish uploade le tarball avec dist/, assets/, src/tokens/, src/tailwind-preset.css, AGENTS.md, README.md, LICENSE.

Cas d'échec possibles

| Situation | Symptôme | Fix | |---|---|---| | Token ajouté au preset sans régénérer | docs:agents:check exit 1, diff visible | npm run docs:agents + commit | | src/components/_xxx.css ajouté sans mapper dans COMPONENT_FILES | Script plante avec un message pointant vers le fichier non mappé | Ajouter l'entrée (voir § Ajouter un composant) | | Tailwind v4 a sorti un nouveau type de token (--ease-*, --breakpoint-*) | console.warn au regen + section "Autres" auto-ajoutée dans AGENTS.md | Pas bloquant ; mettre à jour categorize() dans scripts/build-agents-md.mjs quand possible |

Pré-vérifications locales (optionnel)

Avant de toucher npm version, tu peux simuler :

npm pack --dry-run        # liste exactement ce qui partira (confirme la présence d'AGENTS.md)
npm run docs:agents:check # valide que la doc est synchrone avec les sources

Structure

dist/                 # CSS compilé (mba-design-system.css, mba-tailwind.css)
assets/               # Fonts et SVG (inclus dans le package)
src/
├── tokens/           # Design tokens (CSS Custom Properties)
├── base/             # Reset et styles de base
├── components/       # Classes de composants (.mba-btn, .mba-card, .mba-footer, etc.)
└── utilities/        # Classes utilitaires

Documentation

La documentation interactive est disponible via Storybook.