Contribuer

Comment ajouter un composant au design system — de l’ADR aux portes qualité.

Les sept étapes

Ajouter un composant touche sept artefacts. L’ordre compte : l’ADR débloque tout en aval, et le catalogue est la source de vérité du site de documentation.

ADR d’abord. Modifier le barrel (src/index.ts) ou patterns.ts — ou ajouter tout nouveau composant DS — exige un Architecture Decision Record selon les règles d'escalade du dépôt (voir AGENTS.md). L'ADR nomme le composant, sa couche et son API publique.
Source. Créez packages/design-system/src/components/<catégorie>/<Name>/<Name>.tsx (+ .test.tsx à côté). TypeScript strict, pas de any, jetons uniquement — aucune valeur hex brute ni Tailwind ad hoc.
Export du barrel. Exportez le composant depuis src/index.ts. C'est la seule surface d'import légale — et le barrel lui-même est soumis à ADR.
Entrée patterns.ts. Ajoutez une entrée PatternMeta complète dans src/patterns.ts (slug, name, category, path, description, status, props, interface, assertions, ariaRole, aiHints, examples, antiPatterns, tokens). La forme de l’entrée est documentée ci-dessous — les pages de documentation sont rendues depuis ce catalogue.
Régénérez l’index .ai. Lancez le pipeline EN DEUX ÉTAPES : pnpm exec tsx scripts/build-agent-index.ts && pnpm exec tsx scripts/sync-index-from-patterns.ts. Un seul script laisse l’index périmé.
Docs + stories + test. Ajoutez docs/components/<slug>.mdx (tableau de props correspondant à l’interface source), une story si le composant est visuel, et un test unitaire à côté de la source. La porte de cohérence documentaire (pnpm ds:consistency) échoue sur toute divergence entre ces représentations.
Lancez les portes. pnpm check:all doit être vert avant que la branche puisse être revue (ajoutez --build pour les portes de build). Commits conventionnels, un sujet par branche, revue qa-dev avant fusion dans experimental.

La forme de l’entrée patterns.ts

Chaque champ ci-dessous est requis pour les composants implémentés (tokens optionnel quand le composant ne lit aucun jeton DS) :

{
  slug: "mywidget",                       // kebab-case, unique, = docs route
  name: "MyWidget",                       // PascalCase, = export name
  category: "atoms" | "molecules" | "organisms" | "templates",
  path: "patterns/<category>/<slug>.html",
  description: "One-line summary shown as the page header.",
  status: "implemented",                  // or "planned" | "deprecated"
  props: [ { name, type, required, default, description } ],
  interface: "interface MyWidgetProps { ... }",  // stringified TS
  assertions: [ { type: "aria" | "type", rule, reference } ],
  ariaRole: "img" | null,
  aiHints: "When an agent should reach for this component.",
  examples: [ "<MyWidget />" ],
  antiPatterns: [ "..." ],
  tokens: [ "ep-mywidget-fg" ],           // DS tokens read/defined
}

Règles de modification du barrel

Le barrel (packages/design-system/src/index.ts) et patterns.ts sont l’API publique du design system. Modifier l’un ou l’autre — ajouter, renommer ou retirer des exports — exige un ADR et un bump de version. Les imports profonds sont interdits par le lint ; les consommateurs doivent importer depuis la racine du paquet uniquement.

Corollaire : ne réexportez jamais un composant storefront depuis le barrel DS, et ne déplacez jamais un export sans fenêtre de dépréciation.

Régénération de l’index

L’index agent (.ai/INDEX.json) est généré — ne l’éditez jamais à la main. Après tout changement de patterns.ts, lancez les deux scripts dans l’ordre :

pnpm exec tsx scripts/build-agent-index.ts
pnpm exec tsx scripts/sync-index-from-patterns.ts

build-agent-index.ts reconstruit les métadonnées des composants et les graphes de relations ; sync-index-from-patterns.ts les réconcilie avec patterns.ts. Sauter la deuxième étape provoque des erreurs de bail périmé et de parité dans les portes DS.

Portes qualité

Les commandes ci-dessous doivent passer avant revue :

pnpm check:all        # 21 static gates (imports, stylelint, R-metrics, drift)
pnpm check:all --build   # + tsc / medusa / next build gates
pnpm ds:consistency      # 3-layer docs consistency gate

Un code de sortie 1 d’une porte quelconque signifie que la branche n’est pas poussable. pnpm check:all