saltjsx/build-design-system

Construire un système de design

Le vocabulaire se trouve dans references/glossary.md, les valeurs par défaut pour les interdictions et les largeurs dans references/taste.md. L'aspect de l'application elle-même est la source. N'inventez aucune valeur de couleur, police, ombre, dégradé ou mouvement qu'elle ne possède pas déjà, sauf si la personne a choisi une source de design et confirmé un échantillon.

Les scripts se trouvent dans le dossier scripts/ de cette compétence. Exécutez-les depuis la racine du dépôt avec node, et lisez d'abord --help. scripts/capture.mjs prend les captures d'écran derrière scripts/capture-guard.mjs, qui bloque toutes les écritures, et scripts/pixdiff.mjs les compare. Capture et pixdiff nécessitent Playwright et un Chromium, que scripts/find-chromium.mjs trouve ou explique comment installer.

Étapes

1. Cadrage. Lisez AGENTS.md ou CLAUDE.md, le manifeste et l'arborescence des routes. Écrivez la plainte dans les mots de la personne, le premier changement visible qui y répond, et le flux pilote (celui que la plainte nomme, sinon le flux avec le plus de familles de composants et un formulaire avec un état d'erreur). Ajoutez .design-system/ à .git/info/exclude pour qu'aucune note, capture ou fichier temporaire ne soit jamais commité. Utilisez la branche que la personne a nommée comme branche d'exécution, ou créez-en une et écrivez la branche sur laquelle vous avez commencé dans .design-system/start-branch, ce que land.mjs refuse. Proposez references/taste.md une fois avec ses interdictions non sélectionnées et sauvegardez la copie acceptée dans .design-system/taste.md. Ne demandez rien d'autre. Prenez la valeur par défaut, enregistrez-la comme default (unanswered) et continuez. Terminé lorsque la plainte, le pilote, la branche et le fichier de goût accepté sont consignés.

2. Inventaire et lignes de base. Listez chaque surface, ses états et si elle écrit des données. Comptez les valeurs brutes dans les occurrences (#fff, text-gray-500, p-[13px]) avec scripts/check-system.mjs --no-allowlist --no-self-test --json, et regroupez les composants en familles. Capturez chaque surface dans chaque état aux largeurs la plus étroite et la plus large prises en charge (390 et 1280 par défaut), une navigation fraîche par largeur, avant toute modification. Avec l'application en cours d'exécution (port 3000 ici), listez chaque surface sous forme d'une ligne surface<TAB>route<TAB>states dans .design-system/surfaces.tsv et chaque écriture envoyée par l'application sous forme de METHOD URL dans .design-system/writes.txt, copié depuis son journal réseau, puis exécutez node <this skill>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt. Il refuse de démarrer sans --writes (ou --no-backend pour une application qui n'envoie aucune écriture), prouve que chaque écriture est bloquée avant d'ouvrir le navigateur, sauvegarde l'arbre d'accessibilité de chaque capture et se termine par 1 en cas de capture manquée. Supprimez ce qui n'est utilisé par rien, dans son propre commit. Terminé lorsque chaque surface a une ligne de base ou une raison not captured indiquée.

3. Tokens. Regroupez les valeurs brutes par rôle, nommez-les par objectif et associez chaque surface à son premier plan (references/tokens.md). Exécutez token-mapping jusqu'à ce que chaque valeur brute corresponde à un rôle, une fusion ou une exception listée. Les fusions dans la tolérance sont des décisions. Au-delà de la tolérance, ouvrez une porte par cluster dont la valeur par défaut est la fusion. Effectuez chaque remplacement de valeur identique sur toutes les routes. Terminé lorsque token-mapping signale zéro écart en dehors de la liste d'exceptions et que pixdiff.mjs avec une tolérance de 0 signale 0 % pour chaque surface qu'un remplacement a touchée.

4. Composants. Construisez la famille la plus utilisée de bout en bout en premier (references/components.md). La primitive texte et la primitive petit texte sont livrées dans la vague 1 à côté de Button. Documentez chacune avec component-docs. Montrez la famille à la personne avant le déploiement, car un bogue central découvert après que les écrans consomment le système coûte un balayage (un champ désactivé encore dessiné en rouge, un Combobox 2 px plus haut que Input, des actions de panneau qui ne se répartissent pas, un dépôt de fichier qui échoue en silence). Terminé lorsque chaque composant canonique a une ligne de registre et une documentation, et que ses états désactivé, requis, erreur et texte long sont capturés dans la vitrine et montrés à la personne.

5. Vérifications. Copiez scripts/check-system.mjs et scripts/oklch.mjs dans le dossier scripts/ du dépôt, exécutez --init, puis --init-allowlist une fois. Une règle ne compte qu'une fois qu'elle a été vue en échec : plantez une violation dans un dossier analysé, exécutez --files <plant> --no-allowlist, constatez la sortie 1 nommant la règle, puis supprimez la plante. La liste blanche et le cliquet ne font que diminuer. Une interdiction est livrée avec sa règle de vérification dans le même changement. Les règles de copie sont livrées avec leurs exemptions, limitées aux éléments, pour le texte qui doit rester textuel (citations, termes, chaînes de version) et pour les chaînes de charge utile qu'une machine ou une personne colle ailleurs (une invite, un exemple d'API, une valeur de presse-papiers), car les réécrire modifie ce que quelqu'un d'autre reçoit. Terminé lorsque la vérification se termine par 0 sur un clone propre, --self-test se termine par « all as expected », et chaque règle ajoutée lors de l'exécution a été vue en échec sur sa plante lors de cette session.

6. Pilote. Déplacez le flux pilote avec une modification de code que vous lisez bloc par bloc. Capturez après avec la commande de la ligne de base, les largeurs, les thèmes et les données, en changeant uniquement --kind after, puis exécutez pixdiff.mjs sur les deux dossiers. Une différence inexpliquée est un défaut. Parcourez le flux au clavier, forcez ses états d'erreur et de chargement, puis exécutez ui-review sur les captures après. Terminé lorsque chaque différence dans les captures remonte à une décision ou à une porte. Un changement rendu sans capture est signalé checks-only.

7. Préparation. Avant qu'une migration ne se généralise, les cinq audits ci-dessous tiennent ou portent une exemption enregistrée.

8. Remise. Recalculez les comptes. Rapportez ce que le système couvre en chiffres, d'abord les valeurs par défaut sans réponse, puis ce qui a été trouvé et non corrigé, classé. Proposez la migration avec sa taille. Ne la commencez pas. Terminé lorsque chaque nombre dans le rapport nomme la commande qui l'a produit.

Audits de préparation

Un écart découvert après que les écrans consomment le système coûte un balayage. Un écart découvert avant coûte une ligne. Exécutez-les à la fin de l'étape 5 et à nouveau avant la première vague. Écrivez chaque résultat dans .design-system/readiness.md avec un mot de verdict.

1. Parité des emplacements et des propriétés. Chaque propriété de chaque primitive existante qui a des sites d'appel a une propriété correspondante sur la nouvelle primitive ou une ligne d'écart.
2. Contrats de comportement. Un tableau « ce qui se déclenche quand » par primitive interactive, chaque ligne un test (references/components.md).
3. Parité des tons. Chaque primitive pressable et ligne croisée avec chaque ton de statut plus atténué. Chaque cellule vide est une ligne d'écart ou déclarée non prise en charge.
4. Chaînes épinglées. Chaque requête de test existante par nom de rôle ou texte a un nom par défaut sur la nouvelle primitive et un remplacement d'étiquette.
5. Écrans les plus difficiles. Un site d'appel le plus difficile par famille est rendu dans la vitrine, avec une capture d'écran.

Une famille qui n'est pas prête n'est pas migrée. Ses écrans restent sur l'existant.

Jamais

• Pusher, publier ou déployer, sauf si la personne le demande dans cette session.
• Commiter sur la branche sur laquelle l'exécution a commencé. Créez d'abord la branche d'exécution.
• Stasher ou changer de branche dans un espace de travail sale. Un espace de travail sale obtient la branche d'exécution dans son propre espace de travail (git worktree add).
• Supprimer quoi que ce soit qu'un autre package ou une API publique exporte. Arrêtez-vous et listez-le comme une porte avec ses importateurs.
• Sauter une étape en silence. Si l'application ne se construit pas ou ne s'exécute pas, le rapport indique code-complete, not runtime-verified et nomme ce qui n'a pas été testé.
• Qualifier votre propre travail de verified. Sur un hôte qui ne peut pas démarrer d'autres agents, exécutez les étapes dans l'ordre, vérifiez chacune à partir d'une lecture fraîche du diff et des captures, et marquez ces verdicts self-verified.

Règles

• Les odeurs de valeurs brutes sont #fff, rgb(, text-gray-500, p-[13px] et style={{ padding: 12 }}. Chacune correspond à un jeton sémantique ou à une exception listée.
• Une primitive manquante est une ligne d'écart, jamais une solution de contournement à l'intérieur d'une surface.
• Les fusions de couleurs dans delta E OK 2 et les fusions d'espacement dans 2 px sont des décisions. La largeur de bordure, le poids et l'assouplissement n'ont pas de tolérance.
• Un changement qui ajoute uniquement de la sémantique (un nom, un rôle, aria-current) est une décision. Celui qui supprime ou restructure la sémantique est une porte.
• Faux : {saving ? "Saving..." : "Save"}. Vrai : l'étiquette au repos reste, un indicateur de chargement se trouve à l'intérieur de la même boîte, aria-busy est défini.
• Un correctif qui se répète deux fois devient une règle de vérification ou un script, pas une autre phrase.
• Une ligne de base n'est jamais modifiée pour faire passer un diff. Une vérification qui signale un code correct est corrigée dans la vérification, avec un cas planté qui prouve la correction, jamais en pliant le code.
• Un nombre qu'aucun script n'a produit, ou une vérification jamais vue en échec, n'est pas rapporté.

Terminé

La vérification se termine par 0 sur un clone propre avec chaque règle vue en échec, chaque route répond 200 sur la version de production (capture.mjs --status), le pilote correspond à sa ligne de base à l'exception des changements prévus listés, et chaque nombre de remise provient d'un script.

references/traps.md liste les pièges de comportement par ID. references/tokens.md contient les couches, les noms, les tolérances et les préréglages d'animation.