mikeozornin/skills

Construire un prototype HTML

Construisez chaque prototype dans assets/template.html (dans le répertoire de cette compétence) : un seul fichier HTML autonome. Le template contient déjà toute la coque : en-tête, cadre de navigateur, sélecteur d'état, panneau de notes, carte d'écran, commentaires d'évaluateurs, tokens Koobiq avec les composants k-*, et le moteur d'exécution. L'interface de la coque est en anglais ou en russe, choisie selon la langue du système d'exploitation/du navigateur ; la copie propre du prototype est celle que vous écrivez. Vous n'écrivez que le bloc PROTOTYPE (JS) et la section 5. PROTOTYPE STYLES (CSS). Ne cassez pas le template : ne reconstruisez jamais, ne restylez pas et ne décrivez pas la coque.

Concevoir avant de coder

Un prototype est un outil pour une seule décision, pas une galerie d'écrans. Parcourez ces étapes avant d'écrire prototype.js.

1. Rassemblez le contexte. Qui est l'utilisateur (rôle, expertise), quelle tâche effectue-t-il, qu'est-ce qui la déclenche et à quoi ressemble le « fait » pour lui. Si le produit existe (dépôt, captures d'écran, Figma, documentation, un prototype antérieur), prenez-en la navigation, les termes, les entités et les données, et concevez uniquement le changement. N'inventez pas un produit autour de la fonctionnalité.

2. Nommez la question. Une phrase, ou plusieurs seulement pour un grand prototype : ce que les évaluateurs doivent décider, ou ce qui est le plus douteux dans l'interface (les utilisateurs trouveront-ils X, comprendront-ils Y, Z tient-il avec des données réelles). Pour chaque question, notez ce qu'un évaluateur doit voir pour y répondre et quel état ou données pourraient briser la conception. Si la demande ne nomme aucune question, prenez la décision la plus risquée comme question et soumettez-la à l'auteur à l'étape 4.

3. Écrivez le scénario dans les mots de l'utilisateur, du déclencheur au résultat : « l'analyste voit un pic → ouvre la règle → abaisse le seuil → voit combien d'incidents il y aura ». Ajoutez ensuite uniquement les embranchements dont la question a besoin : annulation, erreur de validation, vide ou première utilisation, et les cas difficiles où des exigences que personne n'avait vues auparavant surgissent : pas d'autorisation, un conflit avec un autre objet, une limite, beaucoup de données, une action que l'état actuel de l'objet interdit. Les étapes deviennent des STEPS, les embranchements deviennent des états, et les conditions transversales (rôle, feature flag, volume de données) deviennent des SWITCHES.

4. Accordez-vous avec l'auteur avant de construire. En un court message, envoyez :

   • la question ;
   • le scénario avec les embranchements et les cas difficiles que vous prévoyez de montrer ;
   • tout ce que vous avez deviné plutôt que pris de la demande ou du produit, sous forme de liste numérotée avec un énoncé par élément, afin que l'auteur puisse répondre par numéro : « 2 — non, l'approbation d'un manager est nécessaire ».

   Attendez la réponse. Sautez cette étape pour les petites modifications d'un prototype existant. Si l'auteur a demandé à ne pas être sollicité, construisez sur vos suppositions et listez-les dans la réponse.

5. Définissez la profondeur de chaque cellule étape × état :

   • complète = sur le chemin de la question : cliquable, chaque état, données de stress ;
   • plausible = contexte : statique mais réaliste ;
   • hors = nommé dans la réponse comme non couvert.

   Utilisez uniquement les états dont la question a besoin : idéal, vide ou première utilisation, partiel, erreur, pas d'autorisation, environ 6 par étape au maximum. Ajoutez le chargement uniquement lorsqu'il montre quelque chose de spécifique (une opération longue, la progression, des résultats partiels). Un échec de chargement vaut rarement un état, mais « non autorisé dans l'état actuel de cet objet » en vaut généralement un. Ne simulez jamais un résultat qui n'est pas conçu.

6. Concevez chaque écran d'abord en mots : son but en une phrase, l'action principale, et ce dont l'utilisateur a besoin pour décider ici, classé par ordre d'importance. Construisez-le ensuite avec les motifs Koobiq standards (tableau, formulaire, panneau latéral, modal, état vide). Mettez la nouveauté uniquement là où se trouve la question ; tout le reste ressemble aux écrans habituels du produit.

   • Chaque action a un résultat visible : ce qui s'est passé et où se trouve l'objet maintenant.
   • Une action destructive nomme l'objet et la conséquence. Les boutons disent généralement le verbe.
   • Une erreur dit comment la corriger et conserve la saisie.
   • Un nom par chose à travers les écrans, le fil d'Ariane, les toasts et l'URL. La copie de l'interface utilisateur est dans la langue de l'utilisateur et suit ux-write s'il est installé.

7. Écrivez les données avant les vues. Utilisez des données de domaine réalistes qui stressent la mise en page : un nom long, un compte 0 / 1 / plusieurs, un statut rare. Utilisez des dates et des valeurs fixes (pas de Date.now() / Math.random()) et pas de lorem ipsum.

Variantes, uniquement lorsque la question est « quelle solution ». Construisez 2 à 3 (max 5) dans VARIANTS au lieu de choisir pour les évaluateurs.

• Elles diffèrent par la structure (mise en page, hiérarchie, action principale), pas par la couleur ou la copie. Si deux maquettes se ressemblent, refaites-en une avec une interdiction explicite (« pas de grille de cartes »).
• Les variantes peuvent partager des données, jamais la mise en page.
• Donnez à chacune un title et une idée d'une ligne dans text.
• Le meilleur retour est « en-tête de B, liste de C ».

Fait quand

Vérifiez le prototype par rapport à chaque élément avant de répondre :

• Chaque chemin montré s'exécute du début à la fin. Il commence là où l'utilisateur rencontre le déclencheur, pas à une connexion ou à un tableau de bord. Chaque embranchement montré se termine, de retour sur le chemin ou à un résultat. Un transfert vers un autre produit ou système est un stub avec un résultat visible (un toast, ou un état comme « Tâche créée dans Jira »), jamais une copie de l'autre interface. Une commande secondaire peut ne rien faire (un élément de menu peut simplement close) tant qu'aucun scénario ne commence à partir de celle-ci.
• Ce qui est discutable est marqué. Chaque élément modifié ou discutable a une note. Lorsque la question est de savoir quelle solution adopter, il y a 2 à 3 variantes qui diffèrent par la structure.
• Rien de superflu. Chaque état, commutateur et note aide à répondre à la question ou teste une hypothèse sur une exigence. Supprimez le reste.

Construire

1. Obtenez les parties modifiables. Avec SKILL_DIR = le répertoire de cette compétence, A=$SKILL_DIR/scripts/assemble.mjs (exécutez avec node, aucune dépendance), répertoire de travail p.ex. /tmp/proto-<nom>/ :

   • nouveau prototype : node $A --split $SKILL_DIR/assets/template.html /tmp/proto-<nom> ;
   • modification d'un existant : node $A --split <fichier>.html /tmp/proto-<nom>. Le réassemblage met également à jour sa coque.

   Cela donne prototype.js (bloc PROTOTYPE de démonstration) et prototype.css (section 5).

2. Réécrivez prototype.js, en remplaçant tout le contenu de démonstration : PROTO, STEPS, SWITCHES, S, NOTES, LINKS (généralement []), données, VIEWS, ACTIONS. Le CSS personnalisé va dans prototype.css. Travaillez en passes :

   1. le chemin principal, cliquable de bout en bout, dans son état idéal ;
   2. les autres états et embranchements ;
   3. les notes ;
   4. Vérifiez et Fait quand.

   Ne peaufinez pas un écran avant que le chemin qui le traverse ne fonctionne.

3. Assemblez : node $A <cible>.html /tmp/proto-<nom>/prototype.js /tmp/proto-<nom>/prototype.css. Il vérifie la syntaxe et les déclarations requises. Livrez uniquement le fichier HTML.

4. Vues : une VIEWS[step](S) par étape qui renvoie une chaîne HTML et bifurque sur S.state / S.sw. Construisez avec les classes k-* ; voir references/koobiq-cheatsheet.md.

   • Chaque état s'affiche entièrement lorsqu'il est ouvert directement. Une ouverture directe (popover, lien de hachage, vignette de carte, note, ←/→, protoCheck) commence à partir du S initial plus la seed de l'état, par exemple { id: 'confirm', title: 'Confirmation', seed: { name: 'Brute force: RDP' } }. Un goto() dans le flux conserve ce que l'utilisateur a tapé. Les VIEWS lisent uniquement S et les données constantes.
   • Superpositions. Un modal ou un panneau latéral est dessiné par-dessus l'écran qu'il couvre, à l'intérieur de la même vue. Une superposition ponctuelle (une confirmation) est un état de cette étape (form/confirm). Une superposition avec son propre sous-flux (formulaire → erreur → confirmation) peut être sa propre étape qui dessine l'écran couvert en dessous. Pour un modal au-dessus d'un panneau, affichez le modal après le panneau : la dernière .k-overlay est celle du dessus, et seuls ses marqueurs s'affichent.
   • Défilement. Un écran plus haut que le cadre du navigateur défile à l'intérieur de celui-ci, comme une page. Une nouvelle étape commence en haut ; un nouvel état ou une nouvelle variante sur la même étape conserve le défilement, afin que les évaluateurs les comparent au même endroit. Une coque d'application (.app-body + .app-content) défile à l'intérieur de .app-content, comme avant.
   • Câblez les clics avec data-act → ACTIONS. Changez d'écran uniquement via goto(step, state) / data-goto, afin que le bouton d'état, la barre d'URL et le hachage restent synchronisés.

5. Notes (3–7) allez uniquement sur les éléments concernés par la question : modifiés ou discutables.

   • Mettez class="changed" data-anchor="note-N" sur l'élément et ${marker(N)} à l'intérieur. Enveloppez les éléments vides ou désactivés dans <span class="k-anchor changed" data-anchor="note-N">.
   • Le text de la note indique ce qui a changé et pourquoi en 1 à 2 phrases. Pour une hypothèse, terminez par « Vérifier : … ».
   • try indique sur quoi cliquer pour le voir.

6. La carte d'écran se construit à partir des états et des transitions. Les transitions proviennent du balisage de chaque état : data-goto, et des appels littéraux goto() / openState() dans les ACTIONS que ses contrôles activés, éléments de menu et superposition supérieure appellent (les contrôles désactivés ne donnent pas de flèche). Un état calculé dans la même action fonctionne si ses identifiants possibles y apparaissent sous forme de chaînes : goto('list', S.q ? 'empty' : 'data'). Une transition derrière une fonction d'assistance, une minuterie ou un événement sur lequel l'utilisateur ne clique pas va dans LINKS : { from: 'report/building', to: 'report/ready', label: 'Rapport prêt' }.

7. Vérifiez (voir Vérification). Corrigez et réassemblez jusqu'à ce que protoCheck() soit propre, puis vérifiez le prototype par rapport à Fait quand.

8. Répondez avec le chemin du fichier, le tableau étape × état, ce qui n'est délibérément pas couvert et toute hypothèse faite après l'accord. Ne décrivez pas la coque.

Commentaires des évaluateurs

L'utilisateur peut coller le Markdown de « Tout copier ». Il nomme le fichier sur la ligne Fichier :. Chaque ## est un écran avec son hachage (#étape/état?commutateurs) ; avec les variantes, il commence par Variante B · Cartes → et le hachage a variant=<id>. La coque l'écrit dans la langue de l'interface de l'évaluateur, il peut donc être en russe : Файл:, Вариант B. Chaque ### est un élément avec son sélecteur à l'intérieur de #view, ses attributs data-* et le numéro de note lié, suivi du commentaire sous forme de citation.

Pour l'appliquer, trouvez l'élément dans VIEWS[step] / ACTIONS de ce fichier (de cette variante), puis modifiez via --split et réassemblez dans le même fichier : les commentaires vivent dans le localStorage du navigateur sous le chemin du fichier.

Règles de la coque

• En-tête = titre court uniquement. Pas de sous-titre, légende, description ou « prototype du flux… » de texte au-dessus du cadre.
• Un seul contrôle d'état : le popover « Étape · État ». Pas de steppers précédent/suivant, de contrôles segmentés par écran, d'onglets au-dessus du cadre ou de raccourcis clavier personnalisés (←/→, Esc et le sélecteur de variante avec 1–9 sont intégrés).
• Les notes vivent uniquement dans aside#notes, à l'extérieur de .browser. À l'intérieur de .app, il n'y a que des marqueurs numérotés. Ne mettez jamais le texte de la note dans des info-bulles ::after, des superpositions ou une colonne « mode d'examen » à l'intérieur de l'application.
• Ne modifiez pas RUNTIME, et ne déplacez pas ou ne restylez pas le deck, la scène, le navigateur, les notes, les commentaires ou la carte d'écran. Le comportement va dans ACTIONS.
• Koobiq par défaut : classes k-* et tokens --kbq-*. Pas de couleurs hex/rgb, de palette inventée (--bg, accents violets) et de style uniquement clair, car le bouton de thème doit fonctionner. Pour un autre système de design, conservez la coque et restylez uniquement l'application.
• Un seul fichier, pas de JS externe.

API PROTOTYPE

Quoi	Comment
Titre / Barre d'URL	PROTO.title, PROTO.url(S)
Grille du popover	STEPS[{id,title,states[{id,title,seed?}]}], SWITCHES[{id,title,options}]
État	S.step, S.state, S.sw[id], S.menu (id du menu ouvert), plus vos propres champs
Naviguer	goto(step, state, patch?) dans le flux (conserve S) ; balisage data-act="goto" data-goto="form/errors". openState(step, state) = ouverture directe (S initial + seed)
Actions	data-act="nom" → ACTIONS.nom(el, e) ; réaffiche sauf s'il renvoie false
Actions intégrées	goto ; close (S.menu = null) ; menu + data-menu="id" (basculer) ; set + data-field + data-value (écrire dans S, fermer le menu). Un menu se ferme également sur Esc, clic en dehors et toute autre action
Entrées	data-model="field" écrit S.field ; data-live réaffiche sur la saisie (le focus et le curseur sont conservés) ; data-live="act" appelle d'abord ACTIONS.act ; data-scroll="key" conserve le défilement
Focus	goto('form', 'errors', { focus: 'name' }) focalise [data-model="name"] une fois
Aides	icon('search'), marker(n, '--x:100%;--y:50%'), tip(html, text, 'k-float--right'), matches(S.q, ...fields), toast(title, {kind, text}), esc(str)
Notes	NOTES[{id, step, state, title, text(html), try}] : step/state indiquent où se trouve l'ancre
Carte d'écran	Construite automatiquement ; LINKS[{from: 'step/state', to: 'step/state', label}] ajoute les transitions que l'analyse ne peut pas voir
Variantes	VARIANTS[{id, title, text, STEPS?, NOTES?, VIEWS?, ACTIONS?, LINKS?, S?, url?}]. Les déclarations globales sont la variante A ; une variante remplace uniquement ce qui diffère (S est fusionné avec le S global). Chacune a sa propre carte d'écran, ses notes et commentaires ; SWITCHES et retour/avant sont partagés. Sélecteur dans l'en-tête, touches 1–9

Vérification

Servez le dossier en arrière-plan (file:// est souvent bloqué) et ouvrez l'URL imprimée plus <fichier>.html dans l'outil de navigation. Rechargez après chaque réassemblage, car un changement de hachage uniquement ne recharge pas le fichier.

cd <dir> && node -e "const fs=require('fs'),T={'.html':'text/html; charset=utf-8','.js':'text/javascript','.css':'text/css','.svg':'image/svg+xml'};require('http').createServer((q,r)=>{const p='.'+decodeURIComponent(new URL(q.url,'http://x').pathname);fs.readFile(p,(e,d)=>{r.writeHead(e?404:200,{'Content-Type':T[require('path').extname(p)]||'application/octet-stream'});r.end(e?'Not found':d)})}).listen(0,'127.0.0.1',function(){console.log('http://127.0.0.1:'+this.address().port+'/')})"

1. Exécutez protoCheck() dans la page (console ou outil de navigation évaluer) avec une largeur de fenêtre de 1440 ou plus. Il doit renvoyer ok: true. Il ouvre chaque combinaison étape × état × commutateur dans les deux thèmes et signale les erreurs de rendu, les écrans vides, le débordement, les marqueurs ou notes cassés, les cibles data-act / data-goto / goto() / LINKS inconnues, les couleurs codées en dur et les restes de template. Corrigez chaque avertissement (états identiques, commutateurs sans effet, données non déterministes, notes en dehors de 3–7, étape non connectée aux autres) ou expliquez-le dans la réponse.
2. Regardez-le dans l'outil de navigation. Vérifiez que chaque écran a l'air plausible avec les vrais jeux de données que les évaluateurs verraient. Vérifiez manuellement chaque état et chaque branche, en particulier : un premier écran (vide), un écran avec beaucoup de données (tableau long, liste longue), une erreur, une confirmation destructive, une étape où un changement de commutateur devrait montrer un contrôle différent et où il ne le fait pas. Vérifiez les transitions que protoCheck ne voit pas : les minuterie setTimeout, les transitions LINKS et les actions personnalisées qui changent d'écran. Vérifiez la navigation arrière/avant du navigateur. Basculez le thème et rafraîchissez. Vérifiez que les notes s'ouvrent, se ferment et cliquent vers leur cible.

Conseils

• Contrôle de version : le squelette du prototype est un arbre d'états. Un nouveau prototype commence à la racine (étape 0) ; une modification commence là où se trouve le changement. La différence détermine la profondeur et les notes : ne construisez que les écrans que la question nécessite. Si la question mud appropriée, par exemple « le bouton Annuler manque », faites l'écran avec le bouton et notez-le. Si la question est « cette page de gestion doit-elle devenir un assistant en trois étapes », construisez les deux en tant que variantes, ou la nouvelle version avec un seul état pour l'actuelle.
• Ne concevez pas une solution complète. Lorsque la question est X, construisez X, pas l'ensemble du produit. Un écran connecté à un flux existant peut montrer un état partiel « vous êtes arrivé depuis X ». Un changement affecte rarement plus de 2–3 étapes.
• Raccourcis : k.fmt() met en cache la mise en page sur le thème actuel. Pour un petit changement pendant l'alignement, faites-le directement dans le navigateur via --split, modifiez, exécutez k.fmt() pour mettre en cache la sortie, puis fusionnez plus tard.
• Interfaces d'IA : bien que des API d'IA soient disponibles, les décisions de conception sont humaines. N'utilisez pas l'IA pour générer la copie de l'interface utilisateur, la structure ou les décisions, seulement pour réduire le bruit dans les données (générer un nom long, un tableau avec 15 lignes, une instruction d'erreur qui a du sens).
• Prototypes pour d'autres systèmes de design : si le produit a son propre système de design, la coque Koobiq reste ; l'application à l'intérieur utilise les classes du système de design du produit. Si le produit possède son propre template, utilisez-le à la place de template.html. Si le système de design est inconnu, utilisez Koobiq (c'est l'option par défaut du template) et notez-le.

Références

• $SKILL_DIR/assets/template.html – la coque, les composants, le thème, les polices et le moteur d'exécution.
• $SKILL_DIR/references/koobiq-cheatsheet.md – tous les composants et classes Koobiq.
• $SKILL_DIR/references/ux-write.md – guide de style pour la copie de l'interface utilisateur (si installé par l'utilisateur).