Du dossier vide à la publication : la structure des fichiers, les jetons de design, les exigences d’accessibilité, les tests et la proposition de publication, étape par étape. Choisissez votre format en haut de page : chaque exemple de code le suit.
Provisoire
Les noms de paquets @unisson/<framework> et les enveloppes <O<Pascal>> (ici OExemple) sont provisoires : ils suivront le nom définitif du produit. La balise native de ce guide, bythium-exemple, sert seulement d’illustration.
Un composant du pack est d’abord une balise native bythium-<nom> ; les enveloppes Vue, React et Svelte la reprennent sans ajouter d’API propre. Ce guide suit un composant fictif, bythium-exemple, du premier fichier à la publication.
Le dossier porte le nom de la balise. Chaque enveloppe a son propre dossier, dans le paquet de son format.
bythium-exemple/
bythium-exemple.js # la balise native
bythium-exemple.css # les styles, écrits avec les jetons
bythium-exemple.test.js # les tests
contrat.json # attributs, slots, événementsLa balise native porte le comportement. L’enveloppe se contente de transmettre les attributs et le contenu, sous les mêmes noms.
class BythiumExemple extends HTMLElement {
static observedAttributes = ['variant'];
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.innerHTML = '<slot></slot>';
}
}
customElements.define('bythium-exemple', BythiumExemple);Le contrat liste les attributs, leurs valeurs permises, les slots et les événements. Le catalogue, les enveloppes et les agents de code lisent ce même fichier.
{
"tag": "bythium-exemple",
"attrs": {
"variant": {
"type": "string",
"enum": ["default", "accent"],
"default": "default"
}
},
"slots": {
"default": { "content": "text" }
},
"events": []
}Un composant n’écrit aucune couleur, aucun rayon ni aucun espacement en dur : il lit les jetons de design, des propriétés CSS que le thème fournit. C’est ce qui lui permet de suivre le thème clair, le thème sombre et la personnalisation décrite dans la page Thèmes.
Chaque valeur visuelle passe par var(). Une variante change de jeton, jamais de valeur brute.
:host {
display: inline-flex;
color: var(--bythium-color-text);
background: var(--bythium-color-surface);
border-radius: var(--bythium-radius);
padding: var(--bythium-space-sm) var(--bythium-space-md);
}
:host([variant='accent']) {
color: var(--bythium-color-on-accent);
background: var(--bythium-color-accent);
}Placez le composant dans un sous-arbre qui force le thème avec data-theme, puis comparez les deux rendus.
<div data-theme="dark">
<bythium-exemple variant="accent">
Aperçu
</bythium-exemple>
</div>Provisoire
Les noms de jetons de cet exemple, comme --bythium-color-surface, sont indicatifs. La liste de référence est celle de la page Thèmes.
Elles font partie du contrat, pas d’une passe de finition.
/* Le focus reste visible, dans les deux thèmes */
:host(:focus-visible) {
outline: var(--bythium-focus-ring);
outline-offset: var(--bythium-focus-offset);
}
/* Le mouvement s’arrête quand le système le demande */
@media (prefers-reduced-motion: reduce) {
:host {
transition: none;
animation: none;
}
}Note
Un attribut aria-* ne répare pas une structure fautive. Vérifiez le composant au clavier seul, puis avec un lecteur d’écran, avant d’écrire ses tests.
Les tests vérifient ce que le contrat promet, pas la façon dont le composant est écrit.
Le fichier de test vit à côté de la balise. Commencez par le contrat : un attribut posé, un comportement observé.
import './bythium-exemple.js';
test('accepte la variante accent', () => {
const el = document.createElement('bythium-exemple');
el.setAttribute('variant', 'accent');
document.body.append(el);
expect(el.getAttribute('variant')).toBe('accent');
expect(el.shadowRoot).not.toBeNull();
});Lancez les tests du paquet de votre format. Une enveloppe passe les mêmes vérifications que la balise native.
$ npm test --workspace @unisson/web-componentsConstruisez le paquet de la balise native, puis celui de chaque enveloppe ajoutée.
$ npm run build --workspace @unisson/web-componentsAjoutez une entrée au journal des versions : le nom de la balise et ce qu’elle apporte, en une phrase.
## À venir
### Ajouté
- `bythium-exemple` : nouveau composant, avec ses enveloppes Vue, React et Svelte.Poussez une branche au nom du composant et ouvrez la proposition dans le dépôt source. La revue porte sur le contrat, l’accessibilité et les tests.
$ git switch -c composant/bythium-exemple
$ git add .
$ git commit -m "Ajoute le composant bythium-exemple"
$ git push --set-upstream origin composant/bythium-exempleNote
La sortie des paquets suit la revue : le composant paraît dans le catalogue avec la version qui le contient.
Page de maquette, contenu cible.Proposer une modification