Pour les agents IA

Ce système de design est conçu pour être compris et utilisé par des agents IA. Les agents observent, analysent, proposent. Les humains approuvent, décident, déploient.

Le dernier mot est toujours humain.

Types d'agents

Quatre rôles dans l'ordre du pipeline de production — de la conception au déploiement.

Agent Figma

Designer Agent

Détecte les dérives dans Figma : instances détachées, descriptions manquantes, espacements et tokens incohérents.

Agent Code

Developer Agent

Détecte les mauvais usages de tokens dans le code, génère les Web Components, ouvre des PRs de correction.

Agent Tests

QA Agent

Exécute les tests d'accessibilité, de régression visuelle, de conformité des tokens avant tout merge.

Agent Docs

Documentation Agent

Génère des changelogs, guides de migration, notes d'accessibilité, mises à jour des guidelines.

Ce que les agents peuvent faire

Autorisé

Lire tous les fichiers du dépôt
Générer du code respectant les contrats
Détecter les dérives de tokens
Proposer des corrections
Créer une branche fix/ ou docs/
Faire des commits sur une branche feature
Ouvrir une PR avec description complète

Interdit

Merger une PR sans approbation humaine
Pusher directement sur main ou develop
Modifier tokens/component.json sans approbation explicite
Inventer des variantes ou tokens non définis
Utiliser des valeurs en dur (hex, px, etc.)
Ignorer les règles d'accessibilité

Ordre de lecture obligatoire

Avant toute action dans ce dépôt, un agent doit lire dans cet ordre :

Fichier	Rôle
`AGENTS.md`	Routeur d'agents — première lecture obligatoire
`DESIGN.md`	Contrat de marque portable
`.claude/rules/project-overview.md`	Contexte général
`.claude/rules/tokens-system.md`	Règles des tokens
`.claude/rules/development.md`	Règles de développement
`guidelines/components/button.md`	Contrat du composant concerné
`.claude/instructions/session-spec.md`	Quick reference pour la session

Règle d'escalade

Toute modification touchant les tokens sémantiques ou de composant déclenche une escalade automatique vers un humain. Les agents ne peuvent pas approuver leurs propres modifications sur ces tokens.

Règle de nommage — rappel

/* ✅ Correct — intention lisible par un agent */
color: var(--sda-component-button-primary-background);

/* ❌ Interdit — valeur brute, aucune intention */
color: #0d74ce;

/* ❌ Interdit — token primitif utilisé directement */
color: var(--sda-primitive-color-blue-11);

Compétences (Skills)

Skill	Rôle
`.claude/skills/ai-ds-composer.md`	Compose des interfaces depuis du langage naturel en respectant les contrats
`.claude/skills/ai-component-metadata.md`	Génère les métadonnées de composant
`.claude/skills/codebase-index.md`	Index du dépôt pour navigation rapide