Was macht UltraExplainer?
Verwandle Code, Systeme, Diffs, Pläne, Daten und Konzepte in eine einzige eigenständige HTML-Seite, die die eine wichtige Idee im ersten Bildschirmausschnitt offensichtlich macht – und sie dann mit verankerten Belegen untermauert. UltraExplainer ist dreierlei, das zusammenwirkt:
- Eine Synthesemethode (das Gehirn) – wie man entscheidet, was gezeigt wird, was betont wird, was weggelassen wird und wie man niemals Struktur zeichnet, die nicht in der Quelle vorhanden ist. Siehe
references/synthesis-method.md. - Das Chameleon Studio (das Handwerk) – ein stabiles, designsprachunabhängiges Komponentenvertrag (
assets/core.css), das durch sieben vollständige Designsprachen (assets/themes.css) umgestaltet wird. Derselbe Diff erscheint als IDE-Randleiste unter Terminal, als liniertes Callout unter Blueprint, als Abbildung unter Editorial. Sie wählen die Sprache passend zum Thema; Glow ist eine Option (Luminous), niemals der Standard. Siehereferences/aesthetic-languages.mdundreferences/component-contract.md. - Eine Interaktivitätsschicht (
assets/ux.js) – eine gemeinsame Zustands-zu-Rendering-Engine, die Schieberegler, Szenario-Umschalter, Schritt-für-Schritt-Durchläufe, sortierbare/filterbare Tabellen, Scroll-Spy-Navigation und geroutete Knoten-Kanten-Diagramme antreibt. Siehereferences/interactivity.md.
Identität: Wahrheit + die richtige Designsprache + geprüftes Handwerk. Nicht „alles glüht“, nicht „Kästchen-und-Pfeile-Suppe“, nicht „eine Wand identischer Karten“.
Wann dieses Skill verwendet werden soll
Greifen Sie zu einer HTML-Seite, wann immer die Ausgabe von Natur aus visuell, relational oder manipulierbar ist und ASCII/Markdown sie verunstalten würde:
- Ein Diagramm, Architekturüberblick oder Knoten-Kanten-Graph darüber, wie etwas zusammenhängt oder fließt.
- Ein Diff / PR-Review (geänderter Code + warum es wichtig ist + Auswirkungsbereich).
- Ein Plan / Anforderungsaudit oder eine Vergleichsmatrix.
- Ein Dashboard mit Metriken oder eine Tabelle mit 4+ Zeilen / 3+ Spalten.
- Ein Konzept-Erklärer, der einen Mechanismus vermittelt, oder ein interaktives Modell, das der Leser fühlen soll, indem er eine Eingabe ändert.
- Eine Folienpräsentation oder ein Projekt-Rückblick zum Kontextwechsel.
Wenn die ehrliche Antwort in einen Satz oder eine einzelne Zahl passt, sagen Sie es im Chat – erstellen Sie keine Seite (die Regel der minimal tragfähigen Erklärung). Wenn Sie doch bauen, geben Sie eine einzeilige Zusammenfassung im Chat und liefern Sie die Datei aus.
Zwei Modi – entscheiden Sie beim Charter
Geben Sie an, in welchem Modus Sie sich befinden (damit der Benutzer korrigieren kann):
- EXPLAIN (Standard) – These zuerst, für Prüfer / Entscheider / Kontextwechsler, die die Schlussfolgerung schnell brauchen. Salienz-Obergrenzen gelten (T0 ≤ 3, T1 ≤ 7).
- TEACH – Frage zuerst, für Lernende, die ein lauffähiges mentales Modell brauchen. Konkret vor abstrakt, Vorhersagen dann Enthüllungen, endet mit einem Transfer-Check. Siehe
references/teaching.md.
Die Methode kurzgefasst
Lesen Sie references/synthesis-method.md, bevor Sie etwas Nicht-Triviales generieren. Die Kurzform:
- Charter – ein Satz: „Dies erklärt auf der Höhe <A0–A4> für , damit sie können“, plus den Modus (EXPLAIN/TEACH). Halten Sie eine Höhe ein.
- These mit Spannung – eine deklarative Behauptung, die der Leser noch nicht kennt (kein Thema). Wählen Sie das Rückgrat (die einzelne Achse, der das Auge folgt).
- Belegverzeichnis – lesen Sie die echte Quelle; für jeden Knoten/Kante/Label/Zahl notieren Sie
{Behauptung, Anker (file:line / Symbol / Git-Ref / Metrik+Datum), Vertrauen (verified|inferred|assumed)}. Kein Anker → es wird nicht als Tatsache dargestellt. Für interaktive Modelle wird jeder Schiebereglerbereich/-standardwert und die Eingabe→Ausgabe-Funktion verankert oder mit „illustratives Modell, nicht gemessen“ gekennzeichnet. - Abgleichen – halten Sie die These gegen widersprechende Beweise; überarbeiten Sie, schränken Sie ein oder zeigen Sie sie. Lassen Sie sie niemals stillschweigend fallen.
- Minimal-tragfähigkeits-Prüfung – über-rendern Sie nicht. Einfache Antwort → Helden-Satz + eine Visualisierung.
- Salienz-Einstufung – T0 (These + Rückgrat, ≤3) / T1 (tragende Unterstützung, ≤7) / T2 (Belege, in
<details>/Hover). Über einer Obergrenze → aufteilen oder herabstufen, niemals quetschen. (TEACH-Modus tauscht Obergrenzen gegen ein Budget wünschenswerter Schwierigkeit.) - Wählen Sie die Designsprache – bewerten Sie die 7 Sprachen nach Thema × Zielgruppe × Medium und notieren Sie eine Zeile:
LANGUAGE: <Name> weil <Thema + Zielgruppe + Medium>. Siehe unten. - Darstellen – fragen Sie zuerst die Manipulierbarkeitsfrage („Soll der Leser fühlen, wie eine Beziehung durch Ändern einer Eingabe wirkt?“); wenn ja, greifen Sie zu einem Modell/Schritt-für-Schritt/Szenario. Andernfalls wählen Sie die tintensparsamste statische Form. Codieren Sie die Größe quantitativ (Größe/Länge/Position), nicht mit gleich großen Kästchen.
- Komprimieren – Weglassung ist die Kunst; kollabieren Sie Wiederholungen („×12 Handler“); zitieren Sie die tragenden Zeilen, nicht ganze Dateien.
- Tore – bestehen Sie alle drei, bevor Sie ausliefern (unten).
Drei Auslieferungstore – Wahrheit übertrifft alles
- WAHRHEIT – jeder Knoten/jede Kante/jede Zahl geht auf einen echten Anker zurück; abgeleiteter/angenommener Inhalt ist sichtbar abgeschwächt; die These wurde gegen widersprechende Beweise abgeglichen; Sie haben die Anker erneut geöffnet. Ein klar gekennzeichnetes „konnte X nicht bestätigen“ ist besser als eine selbstbewusste Erfindung. Eine interaktive Lüge (ein Schieberegler, der eine erfundene Beziehung durchläuft) ist die Kardinalsünde.
- HANDWERK – der Blinzeltest: Aus der Ferne liest es sich als bewusste Designsprache, nicht als neu eingefärbte Vorlage. Genau ein T0-Blickfang.
- BEOBACHTET – Sie haben die Seite tatsächlich gerendert und angesehen. Bauen Sie sie, öffnen Sie sie (headless Screenshot bei ~1280 und ~360), erfassen Sie Konsolenfehler, stellen Sie sicher, dass es kein horizontales Scrollen der Seite gibt und dass die These im ersten Viewport ist, dann korrigieren Sie sich selbst. Hören Sie auf, Checklisten-Eigenschaften zu behaupten, die Sie nie gemessen haben.
So bauen Sie eine Seite (Montage)
Seiten werden von scripts/build.mjs aus einem Body-Fragment in templates/_src/<name>.body.html montiert. Der schnellste Weg: Kopieren Sie die nächstgelegene Vorlage, ändern Sie das preset und passen Sie den Inhalt an.
- Direktive in Zeile 1 (JSON in einem HTML-Kommentar) wählt Sprache und Feintuning:
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset:blueprint | editorial | terminal | instrument | notebook | swiss | luminous(Standardluminous)presets: ["…","…"]→ gibt eine Datei pro Sprache aus (Chamäleon-Demos)theme:light | dark(Standard ist die natürliche Abstimmung des Presets)fx:glow | flat(nur Luminous)head/foot: zusätzliches Markup;<name>.head.html/<name>.foot.htmlSidecars werden ebenfalls zusammengeführt
- Der Build integriert
core.css+themes.css+ux.jsinline, verknüpft die Schriftarten des Presets, setztdata-theme-preset/data-theme/data-fxvor dem Rendering (FOUC-frei) und gibttemplates/<name>.htmlaus. - Ausführen:
node scripts/build.mjs <Name-Filter>(Filter ist ein Teilstring; weglassen, um alle zu bauen). - Die einzigen externen Anfragen der Seite sind Google Fonts (mit System-Fallbacks – das Layout hängt nie von ihnen ab) und, für Mermaid-Seiten, das Mermaid CDN. Die Seite muss auch dann gut aussehen, wenn diese fehlschlagen.
KRITISCH beim Inlinen von JS, das den wörtlichen String
</script>enthält (z. B. ein Beispiel-Snippet): maskieren Sie es als</script>, sonst schließt es das Tag vorzeitig und gibt Quellcode auf die Seite aus.
Die Designsprache wählen
Nach Vorzügen entscheiden, den Grund notieren. Vollständige Bewertungstabelle + Profile pro Sprache in references/aesthetic-languages.md.
| Thema | Standardsprache |
|---|---|
| Architektur, Schemata, Protokolle, Infrastruktur-Topologie | Blueprint |
| Konzepte, ADRs, Post-Mortems, Narrative für Führungskräfte | Editorial |
| Diffs, PRs, CLI-Tools, CI-Pipelines, Logs | Terminal |
| Metriken, Benchmarks, Audits, Dashboards | Instrument |
| Lehren, Walkthroughs, Onboarding, sanfte Erklärer | Notebook |
| Vergleiche, Prinzip/Manifest-Seiten, Statusberichte | Swiss |
| Systemfluss-Demos, Produktvision, Wow-Faktor-Briefings | Luminous (niemals standardmäßig) |
Tie-Breaker: explizite Benutzerwünsche ehren („mach es zu einem Terminal“); rotieren, um Sitzungsmonotonie zu vermeiden; niemals Luminous wählen, nur weil es auffällig ist.
Die Darstellung wählen
Nach der kognitiven Aufgabe und der Datenform entscheiden, nicht nach dem Inhaltstyp. Manipulierbarkeit zuerst. Vollständiger Katalog + Routing in references/representations.md; ehrliche Diagramme in references/charts-honesty.md.
| Aufgabe | Darstellung (Komponente) |
|---|---|
| Ein dominantes Ergebnis / Ja-Nein | Typografischer These-Held (.ux-thesis), vielleicht eine Visualisierung darunter |
| Der Leser soll eine Beziehung fühlen | Parametermodell ([data-playground]) – Schieberegler + gebundene Anzeigen |
| Reihenfolge / Zwischenzustand ist die Bedeutung | Schritt-für-Schritt ([data-stepper]) – Code↔Daten im Gleichschritt |
| Verhält sich je nach Konfiguration unterschiedlich | Szenario-Umschalter (.ux-seg[data-scenario-ctl]) beleuchtet ein Diagramm neu |
| Echte lineare Abfolge | Nummerierte Liste / Flussstreifen (.ux-spine) – kein Flussdiagramm |
| Verzweigender / zusammenführender / zyklischer Fluss | Knoten-Kanten-Graph (.ux-graph, ≤12 Knoten) oder thematisches Mermaid |
| Dichte paarweise Beziehungen | Matrix-Hitzekarte (.ux-matrix) – schlägt einen verfilzten Graphen |
| Code-Änderung / PR | Annotierter Diff + Urteil (.ux-diff + .ux-verdict) + Auswirkungsbereich |
| Konzept / Fehlvorstellung | Naiv-vs.-Richtig-Panels (.ux-compare) + ein durchgerechnetes Beispiel |
| Vergleich / Audit / Matrix | Sortierbare, filterbare Tabelle (.ux-table, th[data-sort], data-ux-filter) |
| Quantitative Metriken | Delta-geführte KPI-Zeile (.ux-kpis) + schlankstes ehrliches Diagramm (.ux-bars/.ux-linechart) |
| Plan / Roadmap | Aktuell→Ziel-Block + risikogestaffelte Zeitleiste (.ux-timeline) |
| Präsentation | Folienpräsentation (templates/slides) |
| Nichts passt | Benutzerdefiniertes Inline-SVG mit Theme-Tokens |
Vorlagen (templates/, mit Quellen in templates/_src/)
| Vorlage | Sprache | Zeigt |
|---|---|---|
chameleon.<preset>.html | alle 7 | Die GLEICHE Erklärung in jeder Sprache gerendert – der Blinzeltest |
blueprint → playground | Blueprint | Parametergetriebenes Modell (Schieberegler, gebundene KPIs/Balken, Voreinstellungen) |
terminal-diff | Terminal | PR-Review: annotierter Diff + Urteil + Auswirkungsbereich |
instrument-dashboard | Instrument | KPI-Kopfzeile + ehrliche Linien-/Balkendiagramme + sortierbare/filterbare Tabelle |
editorial-concept | Editorial | Konzept-Erklärer: Scroll-Spy-Navigation + benutzerdefiniertes SVG + Naiv-vs.-Richtig + Randnotizen |
notebook-teach | Notebook | TEACH-Modus: Schritt-für-Schritt + Vorhersage-dann-Enthüllung + Transfer-Check |
swiss-comparison | Swiss | Entscheidungsmatrix: überdimensionale Ziffern + sortierbare Vergleichstabelle |
luminous-flow | Luminous | Szenario-Umschalter (Treffer/Fehler) + gerouteter Graph + optionaler Glow |
mermaid | beliebig | Thematisches Mermaid mit Zoom / Schwenk / Erweitern |
slides | beliebig | Vollbild-Präsentation mit Tastatur-/Scroll-Navigation |
Referenz-Routing – nur das lesen, was die aktuelle Ausgabe benötigt
| Bedarf | Lesen |
|---|---|
| Wie man entscheidet, was/wie man zeigt (das Gehirn) | references/synthesis-method.md |
| Die 7 Sprachen, Auswahl-Bewertungstabelle, Blinzeltest | references/aesthetic-languages.md |
Token-Stufen, jede .ux--Komponente, Build/Montage | references/component-contract.md |
| Darstellungskatalog + Datenform × Aufgaben-Routing | references/representations.md |
| Schieberegler, Szenario-Umschalter, Stepper, Graphen, Scroll-Spy – die JS-API | references/interactivity.md |
| Ehrliche Diagramme: Zahlenverzeichnis, Kanal-Ranking, Achsenregeln | references/charts-honesty.md |
| TEACH-Modus: Lernzustand, konkret zuerst, Vorhersage-Enthüllung, Transfer | references/teaching.md |
| Aufgabenspezifische Playbooks (PR-Review, Post-Mortem, ADR, Performance-Profil, …) | references/playbooks.md |
| Eigenständigkeit, Überlaufsicherheit, Verifikationsschleife, Auslieferungs-Checkliste | references/self-contained.md |
| Thematisches Mermaid (wann + wie) | references/mermaid.md |
| Folienpräsentationen | references/slides.md |
Invarianten
- Wahrheit übertrifft Schönheit und Handwerk. Verankern oder weglassen; abgeleitete/angenommene Inhalte abschwächen; niemals Ebenen, Symmetrie, Kanten oder Begründungen erfinden. Interaktive Bereiche/Funktionen sind verankert oder mit „illustratives Modell“ gekennzeichnet.
- Eine Sprache pro Seite, nach Vorzügen gewählt und notiert. Sie muss den Blinzeltest bestehen. Glow ist nur für Luminous, über
--fx-*geroutet, so dassdata-fx="flat"es sauber entfernt; kein durchgehendes Atmen/Pulsieren auf statischen Inhalten. - Kein horizontales Seiten-Scrolling.
min-width:0auf Grid/Flex-Kindern; breite Inhalte (Diffs, Tabellen, Mermaid) scrollen in ihrem eigenenoverflow-x:auto-Container. Bei 360px überprüfen. - Beide Themes sehen komponiert aus. Hell ist nachgestimmt, nicht invertiert. Die Seite öffnet sich im gewählten Theme und der Leser kann umschalten (gespeichert pro Preset);
prefers-reduced-motionrespektieren; Tastaturfokus sichtbar halten; druckbar. - Komponenten verwenden nur semantische +
--fx-*-Tokens – niemals Hex-Werte. Neue Looks kommen von Theme-Paketen, nicht von Inline-Farben. - Nie eine
.node-Klasse auf Seitenebene definieren – Mermaid verwendet sie intern. Alle UltraExplainer-Klassen haben das Präfix.ux-. - Beobachten vor dem Ausliefern. Die Seite rendern, sie ansehen, reparieren, was falsch ist. Nicht behaupten, was man nicht gemessen hat.
Abschließende Checkliste
Eigenständiges Dokument am richtigen Pfad · mit dem gewählten preset erstellt · keine Konsolenfehler · kein horizontaler Überlauf bei Desktop oder 360px · Schriftarten degradieren anmutig · die These ist im ersten Viewport offensichtlich mit genau einem Blickfang · Tabellen/Diffs/Diagramme scrollen in ihren eigenen Containern · Theme (und Luminous-Glow) – Umschalter funktionieren · jede Behauptung verankert oder abgeschwächt · die Seite wurde tatsächlich gerendert und inspiziert.