Que fait UltraExplainer ?
Transformez du code, des systèmes, des diffs, des plans, des données et des concepts en une seule page HTML autonome qui rend une idée importante évidente dans le premier écran — puis la prouve avec des preuves ancrées. UltraExplainer est trois choses qui travaillent ensemble :
- Une méthode de synthèse (le cerveau) — comment décider quoi montrer, quoi souligner, quoi couper, et comment ne jamais dessiner de structure qui n'est pas dans la source. Voir
references/synthesis-method.md. - Le Chameleon Studio (l'artisanat) — un contrat de composants stable et indépendant du langage de design (
assets/core.css) re-skiné par sept langages de design complets (assets/themes.css). Le même diff s'affiche comme une gouttière IDE sous Terminal, un encadré réglé sous Blueprint, une figure sous Editorial. Vous choisissez le langage en fonction du sujet ; l'effet lumineux est une option (Luminous), jamais la valeur par défaut. Voirreferences/aesthetic-languages.mdetreferences/component-contract.md. - Une couche d'interactivité (
assets/ux.js) — un moteur état→rendu partagé alimentant des curseurs, des toggles de scénarios, des pas-à-pas, des tableaux triables/filtrables, une navigation scroll-spy et des graphes nœuds-liens routés. Voirreferences/interactivity.md.
Identité : vérité + le bon langage de design + un artisanat vérifié. Pas "tout brille," pas "soupe de boîtes et de flèches," pas "un mur de cartes identiques."
Quand utiliser cette compétence
Utilisez une page HTML chaque fois que la sortie est intrinsèquement visuelle, relationnelle ou manipulable et que l'ASCII/Markdown la déformerait :
- Un diagramme, une vue d'architecture ou un graphe nœuds-liens montrant comment quelque chose se connecte ou circule.
- Un diff / review de PR (code modifié + pourquoi c'est important + rayon d'impact).
- Un plan / audit d'exigences ou une matrice de comparaison.
- Un tableau de bord de métriques, ou tout tableau avec 4+ lignes / 3+ colonnes.
- Un explicateur de concept qui enseigne un mécanisme, ou un modèle interactif que le lecteur doit ressentir en changeant une entrée.
- Un diaporama, ou un récapitulatif de projet pour un changement de contexte.
Si la réponse honnête tient en une phrase ou un seul chiffre, dites-la dans le chat — ne fabriquez pas de page (la règle de l'explicateur minimal viable). Quand vous construisez, donnez un résumé d'une ligne dans le chat et livrez le fichier.
Deux modes — décidez lors de la charte
Indiquez dans quel mode vous êtes (pour que l'utilisateur puisse le corriger) :
- EXPLAIN (par défaut) — thèse d'abord, pour les relecteurs / décideurs / changeurs de contexte qui ont besoin de la conclusion rapidement. Des plafonds de saillance s'appliquent (T0 ≤ 3, T1 ≤ 7).
- TEACH — question d'abord, pour les apprenants qui ont besoin d'un modèle mental exécutable. Concret avant abstrait, prédire puis révéler, se termine par une vérification du transfert. Voir
references/teaching.md.
La méthode, en bref
Lisez references/synthesis-method.md avant de générer quoi que ce soit de non trivial. La version courte :
- Charte — une phrase : "Ceci explique <artefact> à l'altitude <A0–A4> pour <public> afin qu'il/elle puisse <tâche>," plus le mode (EXPLAIN/TEACH). Maintenez une altitude.
- Thèse avec tension — une affirmation déclarative que le lecteur ne connaît pas encore (pas un sujet). Choisissez l'épine dorsale (l'axe unique que l'œil suit).
- Registre de preuves — lisez la source réelle ; pour chaque nœud/lien/étiquette/chiffre, enregistrez
{affirmation, ancre (fichier:ligne / symbole / ref git / métrique+date), confiance (vérifié|inféré|supposé)}. Pas d'ancre → ça ne s'affiche pas comme fait. Pour les modèles interactifs, chaque plage/valeur par défaut de curseur et la fonction entrée→sortie est ancrée ou estampillée "modèle illustratif, non mesuré." - Réconciliez — confrontez la thèse aux preuves contradictoires ; révisez, cadrez, ou montrez-la. Ne la laissez jamais tomber en silence.
- Vérification minimale viable — ne sur-rendez pas. Réponse simple → phrase héroïque + un visuel.
- Hiérarchisation de saillance — T0 (thèse + épine dorsale, ≤3) / T1 (support porteur, ≤7) / T2 (preuves, dans
<details>/survol). Au-dessus d'un plafond → divisez ou rétrogradez, ne réduisez jamais pour faire rentrer. (Le mode TEACH échange les plafonds contre un budget de difficulté souhaitable.) - Choisissez le langage de design — évaluez les 7 langages sur le sujet × le public × le support et enregistrez une ligne :
LANGUAGE: <nom> parce que <sujet + public + support>. Voir ci-dessous. - Représentez — posez d'abord la question de la manipulabilité ("le lecteur doit-il ressentir une relation en changeant une entrée ?") ; si oui, optez pour un modèle/stepper/scénario. Sinon, choisissez la forme statique la moins encreuse. Codez la magnitude quantitativement (taille/longueur/position), pas avec des boîtes égales.
- Compressez — l'omission est l'art ; réduisez la répétition ("×12 gestionnaires") ; extrayez les lignes porteuses, pas des fichiers entiers.
- Portes — passez les trois avant de livrer (ci-dessous).
Trois portes de livraison — la vérité prime sur tout
- TRUTH — chaque nœud/lien/chiffre remonte à une ancre réelle ; le contenu inféré/supposé est visiblement nuancé ; la thèse a été réconciliée avec les preuves contradictoires ; vous avez rouvert les ancres. Un "je n'ai pas pu confirmer X" clairement marqué vaut mieux qu'une fabrication confiante. Un mensonge interactif (un curseur qui manipule une relation fabriquée) est le péché cardinal.
- CRAFT — le test du plissement d'yeux : de l'autre côté de la pièce, ça se lit comme un langage de design délibéré, pas un template recolorié. Exactement un point focal T0.
- OBSERVED — vous avez effectivement rendu la page et regardé. Construisez-la, ouvrez-la (capture d'écran headless à ~1280 et ~360), capturez les erreurs console, assurez-vous qu'il n'y a pas de défilement horizontal et que la thèse est dans le premier viewport, puis corrigez-vous. Arrêtez d'affirmer des propriétés de checklist que vous n'avez jamais mesurées.
Comment construire une page (assemblage)
Les pages sont assemblées par scripts/build.mjs à partir d'un fragment de corps dans templates/_src/<nom>.body.html. Le chemin le plus rapide : copiez le template le plus proche, changez le preset et adaptez le contenu.
- Directive ligne 1 (JSON dans un commentaire HTML) sélectionne le langage et le réglage :
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset:blueprint | editorial | terminal | instrument | notebook | swiss | luminous(par défautluminous)presets: ["…","…"]→ émet un fichier par langage (démos chameau)theme:light | dark(par défaut le réglage naturel du preset)fx:glow | flat(Luminous uniquement)head/foot: balisage supplémentaire ; les sidecars<nom>.head.html/<nom>.foot.htmlsont également fusionnés
- La construction intègre
core.css+themes.css+ux.js, lie les polices du preset, définitdata-theme-preset/data-theme/data-fxavant le rendu (sans FOUC), et émettemplates/<nom>.html. - Exécutez :
node scripts/build.mjs <filtre-nom>(le filtre est une sous-chaîne ; omettez pour tout construire). - Les seules requêtes externes de la page sont Google Fonts (avec des polices de secours système — la mise en page n'en dépend jamais) et, pour les pages Mermaid, le CDN Mermaid. La page doit toujours être correcte si celles-ci échouent.
CRITIQUE lors de l'intégration de tout JS contenant la chaîne littérale
</script>(par exemple, un extrait d'exemple) : échappez-la en\<\/script>ou elle ferme la balise prématurément et déverse la source sur la page.
Choisir le langage de design
Acheminez selon le mérite, enregistrez la raison. Grille d'évaluation complète + profils par langage dans references/aesthetic-languages.md.
| Sujet | Langage par défaut |
|---|---|
| Architecture, schémas, protocoles, topologie infrastructure | Blueprint |
| Concepts, ADR, post-mortems, récits exécutifs | Editorial |
| Diffs, PRs, outils CLI, pipelines CI, logs | Terminal |
| Métriques, benchmarks, audits, tableaux de bord | Instrument |
| Enseignement, procédures pas à pas, intégration, explicateurs doux | Notebook |
| Comparaisons, pages de principes/manifestes, rapports d'état | Swiss |
| Démonstrations de flux système, vision produit, briefs effet waouh | Luminous (jamais par défaut) |
Départages : honorez les demandes explicites des utilisateurs ("fais-en un terminal") ; alternez pour éviter la monotonie de la session ; ne choisissez jamais Luminous juste parce que c'est clinquant.
Choisir la représentation
Acheminez selon la tâche cognitive et la forme des données, pas le type de contenu. Manipulabilité d'abord. Catalogue complet + routage dans references/representations.md ; graphiques honnêtes dans references/charts-honesty.md.
| Tâche | Représentation (composant) |
|---|---|
| Une conclusion dominante / oui-non | Héros typographique de thèse (.ux-thesis), peut-être un visuel en dessous |
| Le lecteur doit ressentir une relation | Modèle paramétrique ([data-playground]) — curseurs + affichages liés |
| L'ordre / l'état intermédiaire est le sens | Pas-à-pas ([data-stepper]) — code↔données en synchronisation |
| Se comporte différemment selon les configurations | Bascule de scénario (.ux-seg[data-scenario-ctl]) ré-illumine un diagramme |
| Séquence linéaire vraie | Liste numérotée / bande de flux (.ux-spine) — pas un organigramme |
| Flux ramifié / fusionné / cyclique | Graphe nœuds-liens (.ux-graph, ≤12 nœuds) ou Mermaid thématisé |
| Relations par paires denses | Carte de chaleur matricielle (.ux-matrix) — bat un graphe en boule de poils |
| Changement de code / PR | Diff annoté + verdict (.ux-diff + .ux-verdict) + rayon d'impact |
| Concept / idée fausse | Panneaux naïf-vs-correct (.ux-compare) + un exemple travaillé |
| Comparaison / audit / matrice | Tableau triable et filtrable (.ux-table, th[data-sort], data-ux-filter) |
| Métriques quantitatives | Ligne de KPI orientée delta (.ux-kpis) + graphique honnête le plus simple (.ux-bars/.ux-linechart) |
| Plan / feuille de route | Bloc actuel→cible + chronologie par risque (.ux-timeline) |
| Présentation | Diaporama (templates/slides) |
| Rien ne correspond | SVG personnalisé en ligne utilisant les tokens du thème |
Templates (templates/, avec sources dans templates/_src/)
| Template | Langage | Démontre |
|---|---|---|
chameleon.<preset>.html | tous les 7 | la MÊME explication rendue dans chaque langage — le test du plissement d'yeux |
blueprint → playground | Blueprint | modèle paramétrique (curseurs, KPI/barres liés, presets) |
terminal-diff | Terminal | review de PR : diff annoté + verdict + rayon d'impact |
instrument-dashboard | Instrument | mât de KPI + graphiques lignes/barres honnêtes + tableau triable/filtrable |
editorial-concept | Editorial | explicateur de concept : navigation scroll-spy + SVG personnalisé + naïf-vs-correct + notes marginales |
notebook-teach | Notebook | mode TEACH : pas-à-pas + prédire puis révéler + vérification du transfert |
swiss-comparison | Swiss | matrice de décision : chiffres surdimensionnés + tableau de comparaison triable |
luminous-flow | Luminous | bascule de scénario (réussite/échec) + graphe routé + effet lumineux optionnel |
mermaid | n'importe lequel | Mermaid thématisé avec zoom / panoramique / extension |
slides | n'importe lequel | diaporama plein écran avec navigation clavier/défilement |
Routage des références — lisez uniquement ce dont la sortie actuelle a besoin
| Besoin | Lisez |
|---|---|
| Comment décider quoi/comment montrer (le cerveau) | references/synthesis-method.md |
| Les 7 langages, grille d'évaluation, test du plissement d'yeux | references/aesthetic-languages.md |
Niveaux de tokens, chaque composant .ux-, construction/assemblage | references/component-contract.md |
| Catalogue des représentations + routage forme des données × tâche | references/representations.md |
| Curseurs, toggles de scénarios, steppers, graphes, scroll-spy — l'API JS | references/interactivity.md |
| Graphiques honnêtes : registre des nombres, classement des canaux, règles des axes | references/charts-honesty.md |
| Mode TEACH : état de l'apprenant, concret d'abord, prédire-révéler, transfert | references/teaching.md |
| Livrets par tâche (review de PR, post-mortem, ADR, profil de performance, …) | references/playbooks.md |
| Autonomie, sécurité du débordement, boucle de vérification, checklist de livraison | references/self-contained.md |
| Mermaid thématisé (quand + comment) | references/mermaid.md |
| Diaporamas | references/slides.md |
Invariants
- La vérité prime sur la beauté et l'artisanat. Ancrez ou omettez ; nuancez le contenu inféré/supposé ; n'inventez jamais de couches, de symétries, de liens ou de justifications. Les plages/fonctions interactives sont ancrées ou estampillées "modèle illustratif."
- Un langage par page, choisi selon le mérite et enregistré. Il doit passer le test du plissement d'yeux. L'effet lumineux est réservé à Luminous, routé via
--fx-*afin quedata-fx="flat"le supprime proprement ; pas de respiration/pulsation continue sur du contenu statique. - Pas de défilement horizontal de la page.
min-width:0sur les enfants grid/flex ; le contenu large (diffs, tableaux, Mermaid) défile dans son propre conteneuroverflow-x:auto. Vérifiez à 360px. - Les deux thèmes sont composés. Le thème clair est réajusté, pas inversé. La page s'ouvre dans son thème choisi et le lecteur peut basculer (persisté par preset) ; respectez
prefers-reduced-motion; gardez le focus clavier visible ; sûr pour l'impression. - Les composants consomment uniquement des tokens sémantiques +
--fx-*— jamais de hex. Les nouveaux looks proviennent de packs de thèmes, pas de couleurs en ligne. - Ne définissez jamais de classe
.nodeau niveau de la page — Mermaid l'utilise en interne. Toutes les classes UltraExplainer sont préfixées par.ux-. - Observez avant de livrer. Rendez la page, regardez-la, corrigez ce qui ne va pas. N'affirmez pas ce que vous n'avez pas mesuré.
Checklist finale
Document autonome au bon chemin · construit avec le preset choisi · aucune erreur console · aucun débordement horizontal sur desktop ou à 360px · les polices se dégradent gracieusement · la thèse est évidente dans le premier viewport avec exactement un point focal · les tableaux/diffs/diagrammes défilent dans leurs propres conteneurs · les bascules de thème (et d'effet lumineux Luminous) fonctionnent · chaque affirmation est ancrée ou nuancée · la page a été effectivement rendue et inspectée.