diorama

Diorama : un petit monde qui bouge

Pour les miniatures narratives détaillées ou les scènes au rendu pixel-perfect, utilisez la compétence séparée diorama-worlds. Cette compétence reste le workflow d'illustration SVG sans dépendance.

Vous réalisez un diorama : une scène construite à partir de blocs sur une base arrondie, vue d'une caméra isométrique, avec quelques éléments qui bougent d'eux-mêmes et répondent au pointeur, dessinée selon un thème. Le thème par défaut, toy, se compose de blocs pastel, d'un soleil chaud, d'ombres douces ; chaque objet est une poignée de boîtes et de cylindres, sans texture, joyeux et lisible au premier coup d'œil. Le même fichier de scène se dessine en soft (crème, plus doux), mono (une teinte d'accent, le reste en nuances d'encre), line (un dessin au trait fin : fonds blancs, bords à l'encre, pas d'ombres), print (tons plats par face et lignes à l'encre, une illustration imprimée) et night (crépuscule, lampes allumées). Chaque champ du thème peut être remplacé : wobble dessine l'encre à main levée, halo est l'ombre douce que la base projette sur la page, accent est la couleur du sujet dans tous les thèmes. Les dix-huit exemples dans examples/ sont la référence, et ils sont au format que vous écrirez.

Vous écrivez une seule chose : la figure, un fichier .js. Le noyau (kit/diorama.js) et la page (bench.html) sont fixes. Ne les modifiez jamais, ne collez jamais de copie modifiée et ne réécrivez jamais ce que le noyau vous donne déjà (une caméra, des lumières, des ombres, une boucle qui dort hors écran, un pointeur, des ressorts, des chemins, des accessoires).

Chaque fichier nommé ci-dessous se trouve dans le dossier de cette compétence. La figure et la page sont écrites dans le répertoire de travail de la personne ; exécutez scripts/build.mjs, scripts/validate.mjs et scripts/look.mjs depuis ce répertoire, en utilisant leur chemin dans ce dossier.

1. Taille et concept

Commencez par décider de la taille, car elle fixe le budget :

Taille	Vit	Scène	Parties	Lignes	Mouvement
hero	haut d'une page d'accueil, un README, une visite guidée	3:2, pleine largeur	150–400 primitives	≤ 420	trois ou quatre boucles indépendantes, quelque chose bouge toujours
card	page de documentation, article de blog, section de fonctionnalité	4:3, ~500px	60–150	≤ 240	une ou deux boucles et une réponse au pointeur
mini	tout petit endroit : état vide, élément de liste, 404, section de paramètres	1:1, 160–240px	15–40	≤ 150	un mouvement ambiant silencieux

Ensuite, lisez references/concepts.md et écrivez le concept en une ligne, avec le thème à la fin :

Nom. Le lieu et ce qui s'y trouve. Ce qui bouge de lui-même. Ce que fait le pointeur. (Pour un mini : ce qui manque.) Thème.

Choisissez le lieu dans le propre univers du produit, pas dans les exemples : un port, une cuisine, un toit, un bureau, une serre, un quai de gare, une rampe de lancement, un coin de rue sont tous des dioramas. Choisissez ensuite le thème en fonction de l'endroit où la figure vivra, pas par goût : toy pour une page produit qui veut chaleur et couleur ; soft pour une page éditoriale ou crème ; mono pour une interface utilisateur de produit qui a sa propre couleur d'accent (passez-la comme accent), une documentation ou tout ce qui se trouve à côté d'un texte dense ; line pour une page minimaliste ou technique, une marque en texte foncé sur fond blanc, ou un état vide qui doit chuchoter ; night pour une page sombre. Lorsque la personne a une couleur de marque, elle va dans accent, qui recolore le sujet dans tous les thèmes ; une deuxième couleur via palette. references/craft.md contient les règles ajoutées par chaque thème.

Ensuite, écrivez la liste des parties, avant tout code : cinq lignes, une par groupe, en nommant chaque objet et les deux ou trois caractéristiques qui le définissent. Sol (la dalle, les zones, les routes, l'eau), structure (ce qui se dresse : bâtiments, étagères, arbres), mobiles (ce qui roule, marche, tourne ou soulève), mobilier (ce qui remplit les bords : lampes, cônes, caisses, bancs, clôtures), lumière (ce qui brille : fenêtres, lampes, balises). Chaque partie repose sur une autre ; rien ne flotte. Une liste de héros compte jusqu'à trente objets, une carte jusqu'à dix, un mini jusqu'à trois. La liste est la scène : si elle semble mince, la figure aussi.

Proposez-en deux ou trois quand il y a quelqu'un à qui demander, et attendez. S'il n'y a personne à qui demander, prenez celle avec le cadre fixe le plus fort et dites laquelle vous avez choisie. Un diorama, un lieu, une histoire. Une scène qui a besoin d'une légende pour être comprise n'est pas encore un concept.

2. Construction

1. Lisez references/craft.md. Les dix règles sont ce qui fait qu'un diorama ressemble à un lieu plutôt qu'à un tas de cubes ; une figure qui en enfreint une n'est pas terminée.
2. Lisez l'index en haut de kit/diorama.js (le commentaire au-dessus de var Diorama). Il liste tout ce que vous pouvez appeler. Ne lisez pas le code en dessous.
3. Lisez l'exemple le plus proche de votre taille et thème : examples/town.js (hero, toy : une ville entière construite à partir de petites fonctions d'aide, plusieurs tours, lumières qui cyclent), examples/island.js (hero, toy : un lieu avec de l'eau, un tour avec un arrêt, mouettes et nuages), examples/farm.js (hero, toy : champs, animaux, un tour avec un arrêt) ou examples/warehouse.js (hero, toy : une cour avec une navette et un quai) ou examples/harbour.js (hero, toy : un quai avec une grue qui soulève des conteneurs sur un cycle de 18 s, un tour de tracteur avec un arrêt et une barrière qui se lève, un remorqueur, un phare, un appui qui démarre un levage, un affichage) ; examples/cafe.js (card, soft : personnes et petites choses), examples/kitchen.js (card, toy : une pièce avec un mur arrière et une fenêtre placée dessus, un réfrigérateur construit comme une coque dont la porte s'ouvre au survol, un grille-pain qui saute sur un appui, une horloge), examples/launchpad.js (card, night : lampes, un événement rare, une fusée qui se démonte sous le pointeur, un appui qui la lance, un affichage qui compte à rebours), examples/server.js (card, mono avec un accent : lumières en rythme, un survol qui illumine tout un groupe) ou examples/rack.js (card, mono avec un accent : un état vide avec une réponse au pointeur) ou examples/assembly.js (card, mono avec un accent : une chaîne de tâches à travers une porte qu'un appui retient, un bras de marquage, un affichage qui compte) ; examples/mailbox.js (mini, toy), examples/seedling.js (mini, line : un état vide dessiné à l'encre), examples/observatory.js (mini, line avec wobble : un dôme qui tourne et un télescope qui regarde), examples/desk.js (mini, line avec un accent) ou examples/vending.js (mini, print : une machine construite comme un cadre autour d'un évidement, des bobines nues, un ventilateur). Ce ne sont pas tous des usines intentionnellement : un diorama est n'importe quel lieu.
4. Écrivez la figure sous la forme <nom>.js dans le répertoire de travail, dans la forme des exemples : un appel Diorama.figure({ … }) avec
   • name : en minuscules, un mot ou avec trait d'union ; size : hero | card | mini.
   • theme : un nom, ou { base: 'mono', accent: '#f2c230', shadows: false, … } pour remplacer n'importe quel champ (palette, accent, lights, shadows, finish, tone, tint, edges, outline, stroke, strokeWidth, round, glow, halo, wobble). Construisez une fois ; le thème est appliqué par le noyau à chaque primitive, donc une figure ne bifurque jamais dessus. Peignez ce qui compte avec pal.accent : c'est la couleur du sujet dans chaque thème, la couleur que mono et line conservent, celle qu'un hexadécimal de marque remplace, et celle que les nuanciers du banc recolorent en direct. Pour une figure line dessinée à la main, ajoutez wobble: 1.4 (px css de tremblement : 1.2 un stylo, 2.5 un feutre).
   • means : une phrase, ≤ 140 caractères, affichée sous la scène. Elle dit ce que la scène montre et ce qui bouge.
   • hint : une ligne, ≤ 90 caractères, ce que fait le pointeur et ce que fait un appui (« Survolez la fusée pour voir ses étages ; appuyez sur la salle de contrôle pour lancer maintenant »). La page l'affiche pour qu'un visiteur sache jouer, et look.mjs appuie sur ce qu'elle nomme.
   • title : le nom de la figure, que la page affiche au-dessus de la scène. Les mots que la propre UI de la personne place autour de la figure (un titre, une ligne, un bouton) sont à elle d'écrire ; la scène n'en porte aucun.
   • camera : { az, el, pad } en degrés. az 45 est la valeur isométrique par défaut ; 30–40 montre une base large dans un hero 3:2. Laissez el à 35.264 sauf si la scène est haute.
   • still : la seconde de la boucle que le mouvement réduit et les vignettes affichent. Choisissez un moment où tout est à un endroit révélateur (le camion au quai, les fourches levées).
   • build({ D, pal }) : construisez la scène une fois avec la boîte à outils et retournez parts : chaque groupe et maille que tick déplacera, plus parts.hot, les groupes que le pointeur peut sélectionner. Donnez à chaque groupe chaud un .name (boat.name = 'boat') : la page l'affiche comme un affichage pendant que le pointeur est dessus.
   • tick(ctx) : à chaque image, posez les parties à partir de ctx.t avec D.phase, D.pulse, D.wave, D.inOut, D.path et D.spring. Répondez au pointeur avec ctx.hover et une pression avec ctx.pressed ou ctx.active (un appui est la façon dont un téléphone répond, donc un hero ou une carte a une chose à presser : un interrupteur, un appel, ou le jumeau du survol). D.apart démonte une chose sous le pointeur et la remet en place. Définissez ctx.read à une courte ligne qui dit ce que la scène fait en ce moment ('camion · au quai') : la page l'affiche comme affichage, et c'est ainsi qu'un visiteur apprend que la scène est un modèle fonctionnel et non une boucle. references/motion.md contient les motifs.
5. Assemblez : node <skill>/scripts/build.mjs <nom>.js écrit diorama-<nom>.html : le banc, le noyau et la figure. Le noyau dessine SVG comme un illustrateur simule la profondeur (une projection isométrique, un ton plat par face, les pièces peintes de l'arrière de la scène vers l'avant, les ombres projetées au sol comme des formes), donc la page ne porte pas de moteur de rendu, n'a pas besoin de WebGL et ne fait aucune requête réseau ; le dessin est vectoriel, net à toute taille, et la page peut le styliser.

3. Vérification

1. node <skill>/scripts/look.mjs <nom>.js. Il construit la page, la valide, l'ouvre dans Chromium sans tête, et écrit diorama-<nom>-look.png : le cadre fixe, trois instants de la boucle, la réponse du pointeur, l'inclinaison de la caméra, une pression, la vignette et la page entière. Il imprime la console, le remplissage, le mouvement, la réponse et la pression sous forme de nombres. Corrigez chaque ÉCHEC, et lisez les lignes PETIT, FIXE, FAIBLE et MUET comme des questions, jusqu'à ce qu'il se termine par 0. La pression atterrit sur le groupe chaud que l'indice nomme après « appuyez », « cliquez » ou « pressez » (ou --press nom, ou --press x,y) ; MUET signifie que l'indice promettait une pression et rien n'a changé. Ajoutez --theme line (ou tout autre nom) pour voir la même figure dans un autre thème ; une figure qui se lit en toy et en line est bien construite. Il imprime aussi clash : des parties mobiles qui traversent d'autres parties ; un véhicule à travers un arbre ou une voiture à travers un bus est un bogue à corriger, des fourches dans un rack ou un drapeau sur sa charnière est correct.
2. Lisez references/look.md, puis la feuille, et répondez à ses questions. Corrigez ce qui échoue, puis revenez à l'étape 1.

look.mjs a besoin d'un navigateur ; il trouve Playwright ou installe playwright-core une fois en dehors de ce dossier. Sans navigateur, exécutez node <skill>/scripts/validate.mjs diorama-<nom>.html après chaque construction et faites le look comme décrit dans look.md sous « Sans navigateur ». Ne remettez pas une page que le validateur rejette. Ne dites pas que le look est terminé si vous n'avez pas regardé.

4. Remise

Remettez diorama-<nom>.html comme la personne l'a demandé : quand elle veut le fichier, donnez le fichier et dites où il se trouve ; sinon, publiez-le comme un artefact si possible. Ensuite, dites, une ligne chacun :

• le concept : le lieu, ce qui bouge, ce que font le pointeur et un appui, et le thème (et comment le changer : theme: dans la figure, ?theme= et ?accent= sur la page, { theme } sur Diorama.mount ; les nuanciers du banc recolorient le sujet en direct) ;
• le cadre fixe : quelle seconde, et pourquoi ce moment ;
• où il devrait vivre (hero, card ou mini) et comment l'intégrer (references/react.md pour React ou Next.js ; une balise <script> du noyau plus la figure et Diorama.mount(fig, { el }) ailleurs) ;
• tout ce que vous n'avez pas pu vérifier (pas de Node, pas de navigateur), clairement.

5. Ajustement

Lorsque la personne demande un changement, modifiez uniquement <nom>.js, puis exécutez à nouveau look.mjs et lisez la nouvelle feuille. La dixième version est tenue à la même exigence que la première.

Ce qui ne va pas

Si vous vous surprenez à	Faites plutôt ceci
utiliser three.js, une lumière, une caméra, un canvas ou WebGL	il n'y en a pas : le noyau dessine SVG ; utilisez D.box, D.cyl, D.props.*, o.M pour un vecteur, et ctx
écrire requestAnimationFrame, setInterval ou une animation CSS	posez tout à partir de ctx.t dans tick (règle 07)
déplacer une chose avec position.x += speed * dt	mettez-la sur un D.path et lisez sa distance à partir de D.phase(t, period), pour que la boucle soit sans couture et que le cadre fixe soit reproductible (règle 08)
écrire un mot, un nombre ou une flèche dans la scène	dites-le avec le titre ou les means ; la scène ne porte aucun mot, pas même un panneau (règle 10)
utiliser une texture, un dégradé, une lueur ou une 15e couleur	un bloc de plus dans une couleur de palette ; pal.* a ce dont vous avez besoin (règles 03 et 04)
écrire if (theme === 'line') dans la figure	le noyau teinte, trace et éclaire chaque primitive selon le thème ; une figure est la même dans les cinq
coller une couleur de marque sur vingt parties, ou peindre le sujet avec un nom de palette	peignez le sujet avec pal.accent et mettez l'hexadécimal de la marque dans accent, une fois, dans la déclaration ; palette: { cobalt: … } pour une deuxième couleur
une réponse au survol et rien pour un doigt	donnez à une chose une pression (ctx.pressed, ctx.active) : le survol prévisualise, un appui confirme (motion.md, « La pression »)
une figure line qui se lit comme un export CAO	wobble: 1.4 dans le thème : l'encre se courbe et dépasse comme une main
désactiver halo parce que la base « a l'air sale »	le halo est ce qui pose le diorama sur la page ; baissez-le (.1) sur un fond chargé, gardez-le
un affichage qui dit ce que dit le titre	ctx.read est l'horloge en mots : la phase, l'arrêt, le compte, à partir du même T qui pose les parties
construire la base après la scène, ou pas du tout	D.slab en premier : les ombres ont besoin d'un endroit où atterrir (règle 01)
une scène qui se lit comme une grille de cubes identiques	donnez à chaque objet les deux ou trois caractéristiques qui le définissent (règle 05)
un mini avec huit choses dedans	un objet, un mouvement ambiant (concepts.md, « Un mini »)
un hero où tout bouge au même tempo	trois boucles avec des tempos différents, ou une chose qui mène et d'autres qui suivent (motion.md, « Les trois rythmes »)

…

[le contenu est tronqué volontairement comme l'original]