Un agent de code ne devine pas l’interface : il lit le catalogue, choisit le composant d’après « quand l’utiliser » et « quand l’éviter », écrit le code dans le framework du projet, puis vérifie son résultat. Ce guide suit ces quatre gestes, avec un exemple de session dans un terminal.
Provisoire
La commande unisson et ses sous-commandes catalog et validate sont provisoires, comme les noms de paquets @unisson/<framework> : elles suivront le nom définitif du produit. Les balises natives gardent leur nom bythium-<nom>.
Le pack se décrit lui-même. Chaque composant a une fiche lisible par une machine : son résumé, quand l’utiliser, quand l’éviter, ses attributs avec leurs valeurs permises, ses emplacements et ses événements. L’agent travaille à partir de ces fiches, pas à partir de sa mémoire.
D’abord l’index, ensuite la fiche.
L’index donne une ligne par composant : le nom de la balise, son niveau et un résumé d’une phrase. L’agent y repère quelques candidats sans charger tout le catalogue.
Pour chaque candidat, l’agent lit ensuite la fiche complète. C’est elle qui fait foi : un attribut ou une valeur absents de la fiche n’existent pas.
# L’index : une ligne par composant
$ npx unisson catalog
# La fiche d’un composant candidat
$ npx unisson catalog bythium-buttonDeux champs de la fiche servent à choisir. « Quand l’utiliser » (useWhen) décrit le besoin que le composant couvre. « Quand l’éviter » (avoidWhen) décrit les cas voisins et nomme le composant à prendre à la place.
useWhen, le composant est retenu.avoidWhen, l’agent suit le renvoi et lit la fiche du composant nommé.{
"tag": "bythium-<nom>",
"summary": "…",
"useWhen": "…",
"avoidWhen": "…",
"attrs": { … },
"slots": { … },
"events": [ … ]
}Note
Demandez à l’agent de citer le useWhen qui justifie chaque choix : la relecture en devient plus rapide, et un mauvais choix se voit tout de suite.
L’agent regarde le projet avant d’écrire : le paquet @unisson/<framework> déjà installé lui dit quel format produire. Le contrat reste le même partout ; seule la forme change, balise native en HTML ou enveloppe typée en Vue, React et Svelte.
Les noms d’attributs et leurs valeurs viennent de la fiche, jamais d’une API propre à un framework.
<bythium-button variant="primary">
Enregistrer
</bythium-button>La validation compare le fichier aux fiches : balises connues, attributs existants, valeurs permises, emplacements valides.
$ npx unisson validate <fichier>Chaque diagnostic donne un chemin, un code et un message. L’agent relit la fiche du composant visé plutôt que d’essayer une autre valeur au hasard.
L’agent corrige, puis relance la même commande, jusqu’à obtenir ok à true et une liste de diagnostics vide.
Note
La validation vérifie le contrat, pas l’intention. Une personne relit toujours le résultat : le bon composant au bon endroit, les bons libellés, le bon parcours au clavier.
Voici la suite complète pour une demande simple, un bouton « Enregistrer ». Les sorties sont abrégées par des points de suspension.
La session compte une erreur, et c’est voulu : l’agent la lit, revient à la fiche, corrige, puis valide de nouveau.
# Découvrir : l’index du catalogue
$ npx unisson catalog
bythium-button L1 Bouton natif avec variantes, tailles…
…
# Choisir : la fiche du candidat
$ npx unisson catalog bythium-button
{ "useWhen": "…", "avoidWhen": "…", "attrs": { … } }
# Écrire le fichier, puis vérifier
$ npx unisson validate <fichier>
{ "ok": false, "diagnostics": [{ "path": "…", "code": "…", "message": "…" }] }
# Corriger d’après la fiche, puis vérifier de nouveau
$ npx unisson validate <fichier>
{ "ok": true, "diagnostics": [] }Page de maquette, contenu cible.Proposer une modification