# Contribuer au DSMMG

Merci de prendre le temps de contribuer. Ce guide décrit le workflow
attendu pour ajouter / modifier un composant, fixer un bug, ou faire
évoluer le design system.

## Setup local

```sh
git clone https://git.dinawo.fr/ManageMate-Group/DSMMG.git
cd DSMMG
pnpm install
pnpm build           # build tous les packages dans le bon ordre
pnpm storybook       # lance Storybook localement (port 6006)
pnpm demo            # lance la demo Vite (port 5180)
pnpm --filter @managemate/react test:watch
```

Pré-requis : Node ≥ 20, pnpm ≥ 9, Git.

## Workflow d'une PR

1. **Créer une branche** depuis `main` :
   - `feat/<name>` — nouvelle fonctionnalité
   - `fix/<name>` — correction de bug
   - `chore/<name>` — outillage, refacto sans surface publique
   - `docs/<name>` — documentation
2. **Coder + tests** :
   - Tests unitaires (`*.test.tsx`) avec Vitest + axe-core
   - Stories Storybook (`*.stories.tsx`) avec autodocs
   - Doc MDX pour les composants publics
3. **Ajouter un changeset** : `pnpm changeset` (sélectionner les
   packages impactés et le bump approprié — patch / minor / major).
4. **Push** + ouvrir la PR sur `main`.
5. **CI doit passer** :
   - lint + typecheck
   - tests Vitest
   - axe-core (pas de violation a11y)
   - lint contraste WCAG (`pnpm lint:contrast`)
   - build Storybook + visual regression
   - bundle size budget (`pnpm size`)
6. **1 review minimum** d'un CODEOWNER avant merge.

## Conventions de code

### Naming

- **Tokens couleur** : `--mmg-color-*` (jamais `--mmg-color-synapse-*`
  directement dans un composant — toujours `--mmg-color-accent-*`).
- **Classes CSS** : `mmg-<comp>` BEM-like (`mmg-btn`, `mmg-btn--primary`,
  `mmg-btn__icon`).
- **Utilitaires CSS** : `mmg-u-*` (`mmg-u-stack`, `mmg-u-text-primary`).
- **Composants React** : PascalCase (`Button`, `ProfileHeader`,
  `MetricCard`). **Un fichier par composant**, pas de monolithe.
- **Tests** : `<Component>.test.tsx`, **stories** : `<Component>.stories.tsx`.

### Sémantique

- Choisir le tag HTML selon **la sémantique**, pas selon la taille
  visuelle. Un titre de page reste `<h1>` même s'il est stylé en
  `display-xl`.
- Préférer `<button>` à `<div onClick>`. Préférer `<a href>` pour la
  navigation.

### Accessibilité (non-négociable)

- Tester en clavier (Tab, Shift+Tab, Esc, flèches, Enter, Espace).
- Tester avec un lecteur d'écran si possible (NVDA / VoiceOver).
- Tester en zoom 200 % et reflow 320px.
- Tester avec `prefers-reduced-motion` activé.
- Toute couleur d'info doit être redondée avec icône / texte / pattern
  (RGAA 9 — couleur seule interdite).
- Aucun `outline: none` sans focus visible alternatif.
- Cible tactile ≥ 44×44 (WCAG SC 2.5.5).

## Ajouter un nouveau composant

1. Créer `packages/react/src/<Component>.tsx` (un fichier, exports
   nommés, types exportés).
2. Si CSS dédié : `packages/css/src/components/<comp>.css` + l'importer
   dans `packages/css/src/index.css` avec `layer(components)`.
3. **Story** : `storybook/stories/<Component>.stories.tsx` — au minimum
   un default + variants + states (default/hover/focus/loading/empty/
   error/disabled).
4. **Tests** : `packages/react/src/<Component>.test.tsx` — render, axe,
   clavier, interactions critiques.
5. **Doc MDX** : `docs/src/content/docs/components/<component>.md` —
   anatomie, props, do/don't, accessibilité.
6. **Export** dans `packages/react/src/index.tsx`.
7. **Changeset** minor.

> **Un composant non documenté n'est pas livré.**

## RFC pour les changements majeurs

Voir [RFC process](docs/src/content/docs/contrib/rfc.md). Une RFC est
requise pour :
- nouveau composant non-trivial (DataTable v2, Calendar, Editor…)
- breaking change sur l'API publique
- refonte d'un token ou d'un groupe de tokens
- nouvelle dépendance externe
- changement architectural

## Versioning (SemVer strict)

- **major** : breaking change sur l'API publique
- **minor** : addition non-breaking (nouveau composant, nouvelle prop)
- **patch** : bugfix, doc, perf interne sans surface publique

Les 4 packages versionnés (`tokens`, `css`, `react`, `icons`) sont
**fixed** (même version) — pas d'incompatibilités cross-package.

## Code de conduite

Voir [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Toute communication
toxique, harcèlement, ou comportement excluant entraîne l'exclusion du
projet.

## Sécurité

Les vulnérabilités doivent être signalées en privé. Voir
[SECURITY.md](SECURITY.md).

## Licence

Tout contribution est faite sous la licence du projet
(voir [LICENSE](LICENSE)). En soumettant une PR, vous accordez à
ManageMate Group le droit d'utiliser votre contribution dans le cadre
du DSMMG.