Skip to main content

Contribuer au Design System

Ajouter un token​

  1. ADR si rupture : si le token introduit une nouvelle dimension (nouveau type d'ombre, nouvelle échelle de spacing, thème clair…), écrire d'abord un ADR dans docs-site/docs/adr/
  2. Éditer src/app/globals.css : ajouter la variable sous le commentaire de section approprié 
    :root {
      /* Accent ambre/or */
      --color-accent-strong: #B45309;
    }
  3. Régénérer la doc : 
    npm run docs:generate-tokens
  4. Vérifier la page correspondante (Couleurs, etc.) : le nouveau token apparaît avec swatch + valeur
  5. Utiliser le token dans au moins un composant pour valider son usage pratique

Ajouter un composant UI​

  1. TDD d'abord (CLAUDE.md) : écrire le test rouge dans src/components/ui/__tests__/<kebab>.test.tsx
  2. Créer src/components/ui/<kebab-case>.tsx
    • Server Component par défaut (pas de 'use client' sauf si hooks / état)
    • Utiliser les tokens CSS (var(--color-*)) plutôt que des valeurs en dur
    • Typer les props via une interface <Name>Props exportée
    • JSDoc sur chaque prop (le script l'extrait)
  3. Régénérer les props : 
    npm run docs:generate-component-props
  4. Créer la page doc docs-site/docs/design-system/components/<kebab-case>.md : 
    ---
    title: <Name>
    ---

    import Props from '@site/docs/design-system/_generated-props/<kebab-case>.mdx';

    # <Name>

    Description courte (1-2 phrases).

    ## Props

    <Props />

    ## Exemples

    <!-- Exemples visuels ou code -->

    ## Accessibilité

    - ...

    ## Ne pas faire

    - ...
  5. Ajouter l'entrée dans docs-site/sidebars.ts (section designSystem / composants)
  6. Vérifier : 
    npm run docs:build

Ajouter un pattern​

Un pattern est une manière d'assembler plusieurs composants pour résoudre un problème récurrent (formulaire, état vide, tableau filtrable…).

  1. Créer docs-site/docs/design-system/patterns/<kebab>.md
  2. Structure recommandée :
    • Problème que le pattern résout
    • Composants utilisés
    • Exemple (capture ou code)
    • Variantes si applicable
    • À faire / à ne pas faire
  3. Ajouter l'entrée dans sidebars.ts

Refuser les incohérences​

L'agent docs-specialist refuse :

  • Une page sans entrée dans sidebars.ts
  • Un composant documenté sans props extraites via le script
  • Un token documenté manuellement qui devrait être généré
  • Une duplication de contenu entre sections

Ces refus sont intentionnels : ils garantissent la cohérence à l'échelle de ~75 pages.

Voir aussi​