Lieferung von Visualisierungs-Websites mit Scrollytelling
Kernprinzip
Erst klären → Plan erstellen → Unabhängig prüfen → Selbst verifizieren → Runtime korrigieren → Inkrementell umsetzen → Jeder Batch deploybar. Jegliche Abnahmekriterien wie „nicht ruckelt“ oder „sieht gut aus“, die nicht durch Skripte überprüfbar sind, sind verboten: Jedes Kriterium muss mit einem Headless-Browser-Assertion überprüfbar sein.
Dieses Skill besteht aus 6 Komponenten:
- Diese Datei: Sieben-Phasen-Workflow + Fragekatalog + Review-Vorlage + Berichtsformat
references/verify-recipes.md: 13 Laufzeitmesstechniken + Koordinaten-/Pipeline-Fallstrickereferences/pitfalls.md: 22 dokumentierte Fallstricke (Phänomen → Ursache → Reparatur → Allgemeine Regel)references/animation-components.md: Integrationsmuster für Drittanbieter-Canvas-Komponenten (Cache-Key / Cleanup / Mount-Bedingungen / Standbild-Abnahme)references/content-sourcing.md: Zahlen müssen eine Quelle haben oder explizit als Lehrbeispiel gekennzeichnet sein (Pflicht für populärwissenschaftliche/medizinische/datengetriebene Inhalte)assets/:long-stage.tsx+long-stage.css(Dreischicht-Struktur der langen Bühne),tokens.css(Dual-Themes),verify-skeleton.mjs.md(Verifikationsskript-Gerüst)
Trigger-basierte Leseanleitung: Werden Drittanbieter-Animationen eingebunden → lies animation-components; enthält die Seite konkrete Zahlen/wissenschaftliche Aussagen → lies content-sourcing; ansonsten lese die Phasen der Reihe nach.
Phase 1: Erst klären, nicht raten
Wenn es unbelegte Annahmen zu den Anforderungen gibt, ist das Schreiben von Code verboten. Stelle die ausstehenden Entscheidungen als Baum dar, frage nur nach Entscheidungen, deren Vorbedingungen bereits geklärt sind; jede Frage muss eine empfohlene Antwort + Begründung enthalten, damit der Nutzer direkt mit Ja antworten kann. Was du selbst herausfinden kannst (Dateien lesen, Befehle ausführen, Doku suchen), frage nicht den Nutzer.
Fragenkatalog (in Abhängigkeitsreihenfolge, nach Projekt anpassbar):
- Was genau ist das Thema (Domäne/Subdomäne/Präsentationswinkel)?
- Für wen ist es (bestimmt die Begriffsdichte und Fehlertoleranz)? – „Prüfer-/Bewerter-Perspektive“ ist eine implizite Anforderung, die aktiv erfragt werden muss: „Wer entscheidet, ob es gut ist?“ ist effektiver als „Wie tief soll ich schreiben?“
- Was soll der Betrachter beim ersten Blick auf die Seite verstehen? (Ein Satz als Leitmotiv; Auswahl aus den Typen: „Zahlen-Schock / Frage-Interaktion / Kontrast-Überraschung“)
- Datenquelle: echt belegbar / Lehrbeispiel / gemischt
- Visueller Grundton: dunkel immersiv / hell professionell / hoher Kontrast
- Bereitstellungsform: Single-Page Landing / Mehrkapitel-Scrollen / Mehrere Seiten
- 3D nötig? (Nutzen vs. Abnahmekosten)
- Interaktionsverstärkung: Lange Bühne / Mausfolge / Drittanbieter-Animationen
- Projektverzeichnispfad
- Wie sollen Referenzmaterialien des Nutzers umgesetzt werden? (Quellcode-Integration vs. nur visuelle Referenz)
- Online-URL / Deploy-Methode
Nachträgliche Entscheidungsänderungen sind normal (z. B. hell → Dual-Themes). Die Entscheidungstabelle muss Einträge „alte Entscheidung verworfen“ enthalten, nicht stillschweigend überschreiben.
Phase 2: Plan erstellen, auf Review warten
Schreibe den Plan nach docs/plan-<thema>.md und committe ihn. Er muss enthalten:
- Ist-Analyse: Bei Änderungen an bestehenden Projekten jede Aussage mit
file:lineversehen; bei neuen Projekten eine Dateiliste erstellen - Entscheidungstabelle D1–Dn: Jede Instanz sagt, warum diese Wahl getroffen wurde, nicht „ich werde das tun“
- Batch-Aufteilung: Jeder Batch muss unabhängig deploybar und rückrollbar sein
- Abnahmekriterien müssen Skript-geprüft werden können: „nicht ruckeln“ → „rAF-Frame-Intervall-Median ≤33ms“; „sieht gut aus“ → „benachbarte Karten haben blur(3px) opacity .55“
- Explizit: „Was NICHT gemacht wird“: Klare Ausschlüsse, um Aufwände während der Umsetzung zu vermeiden
Phase 3: Explizite Bestätigung abwarten
„Hm“, „OK“, „geht klar“ gelten als vage – noch einmal nachfragen; „mach du mal“ ist keine Bestätigung.
Phase 4: Unabhängiges Review
Setze einen Sub-Agenten mit völlig neuem Kontext auf das Review des Plans an. Er darf nicht nur den Plan sehen, sondern muss auch den echten Code und die Verifikationsskripte erhalten.
Du prüfst gerade einen Plan, der noch nicht umgesetzt wurde. Deine Aufgabe ist es, Probleme zu finden, nicht den Plan zu genehmigen.
## Pflichtlektüre
- Plan-Dokument: <Pfad>
- Realer Code: <Projektwurzel>, Schwerpunkt <Datei>
- Verifikationswerkzeug: <Skriptpfad>
## Priorisierte Prüfung
1. Faktische Korrektheit (höchster Wert): Ist jede `file:line` korrekt? Trifft jede Aussage über das bestehende Verhalten zu? Bei Fehlern mit realen Codezeilen widerlegen.
2. Vollständigkeit: Behauptet N Entscheidungen umzusetzen, prüfe einzeln ob alle durch Aufgaben abgedeckt sind.
3. Interne Widersprüche: Verspricht Abschnitt A, was Abschnitt B verbietet?
4. Konkrete technische Risiken: Nenne 3-5 Punkte, bei denen dieses Projekt am ehesten scheitert.
5. Lücken: Was steht nicht im Plan, muss der Umsetzer selbst erfinden?
6. Prüfbarkeit der Abnahmekriterien: Ist jedes Kriterium objektiv beurteilbar? Welche sind schwammig?
7. Batch-Reihenfolge: Gibt es Abhängigkeiten von späteren Batches? Gibt es Dinge, die in keinem Batch stehen?
## Ausgabe
Nummerierte Liste, jede Instanz: Schweregrad (BLOCKING/MAJOR/MINOR), Ort, Fehler (mit Beleg), Reparatur.
Abschließende Bewertung: Kann die Umsetzung beginnen?
Ändere keine Dateien. Genehmige nicht aus Höflichkeit – ein Review, das nichts findet, ist gescheitert.
Phase 5: Review-Ergebnisse selbst verifizieren
Sub-Agenten machen Fehler. Überprüfe jede Beanstandung manuell im Code, bevor du Änderungen vornimmst. Geh davon aus, dass eine Beanstandung falsch ist.
Bisher beobachtete reale Fälle:
- Ein Review mit 16 Beanstandungen war zu 100% korrekt (7 MAJOR + 9 MINOR, darunter 3, die ergaben, dass der Verifikationsmechanismus selbst defekt war – Assertion war entweder immer wahr oder schlug nie fehl).
- Ein anderer Fall: Der Agent ordnete die Idle-Erkennung von Komponente A fälschlich Komponente B zu, was durch Lesen der Quellcodezeile aufgedeckt wurde.
Phase 6: Runtime-Korrektur
Der Review-Agent kann nur aus dem Code schließen, nicht die Laufzeitgrößen/Framerate/Composite-Verhalten messen. Verwende einen Headless-Browser für konkrete Messungen. Alle in die Dokumentation geschriebenen Zahlen müssen gemessene Werte sein.
Siehe references/verify-recipes.md.
Phase 7: Inkrementelle Umsetzung
Nach jedem Batch: vollständige Abnahme durchführen → git tag → committen. Die Commit-Nachricht enthält: „was geändert wurde, warum, und die Messdaten“.
Der Bericht hat feste drei Abschnitte:
- Was getan wurde: Dateiliste + Messdaten (nicht „erledigt“, sondern
pinTop=68.0,travel-Abweichung 0.0px) - Was fehlt noch
- Was wurde entdeckt: Planfehler oder Codefehler? In welcher Zeile?
Minimalstruktur des Abnahmesystems (dieses Projekt: 45 Assertions / 7 Unit-Tests)
| Ebene | Werkzeug | Zuständigkeit |
|---|---|---|
| Typen | tsc --noEmit | Typvollständigkeit. Vitest komplett grün ≠ baufähig, esbuild entfernt Typen. |
| Unit | vitest run | Datenintegrität (Quellenfeld nicht leer, beide Typen müssen gleichzeitig existieren), reine Funktionen |
| Runtime | scripts/verify.mjs (puppeteer-core + System-Chrome) | Layout-Overflow, Kontrast, Framerate, Animationsstatus, Degradationspfade |
| Build | npm run build | Das echte Produkt lässt sich bauen |
Assertions müssen fehlschlagen können. Nach dem Schreiben jeder Assertion kurz den Code umkehren und prüfen, ob sie FAIL wird – sonst weißt du nicht, ob sie immer wahr ist oder wirklich testet.
Cross-Viewport-Assertions müssen setViewportSettled verwenden. page.setViewport garantiert nur, dass die Viewport-Größe abgeschickt wurde, nicht dass das Reflow abgeschlossen ist; ein direktes Lesen von scrollWidth kann den alten Wert vor der Verengung liefern, was sporadische FAILs verursacht (siehe references/pitfalls.md, Punkt 21). Solche sporadischen Probleme zeigen sich erst bei wiederholter Ausführung – einmal alles grün ist kein Abnahmebeweis.
Häufige Missverständnisse
| Missverständnis | Realität |
|---|---|
| „Unit-Tests bestanden, also auslieferbar“ | esbuild entfernt Typen, tsc kann Fehler melden, während vitest noch grün ist |
| „Screenshot-Diff erfasst alle visuellen Änderungen“ | Headless-Screenshot-Pipelines erfassen möglicherweise keine DOM-Neuzeichnungen, sondern nur Canvas-Texturen |
| „500ms Polling reicht“ | scroll-behavior:smooth + scrub:1 sind asynchron; explizit instant + explizites Pollen bis Bedingung erfüllt |
| „Responsiv bedeutet einmal Viewport ändern und testen“ | Pin-/Touch-/CDP-Zustände werden Cross-Test-Case verschleppt; neue Seite oder neuer Browserprozess nötig |
| „Reduced-motion heißt Animationen aus“ | Animationen aus, aber keine Information darf fehlen; Assertion, dass die Textmenge gleich bleibt |
Beziehung zu anderen Skills
- Visuelle Richtung / Anti-AI-Look:
frontend-design,design-taste-frontend - Plan- und Review-Disziplin:
writing-plans,plan-sds-review - Fehlerlokalisierung:
systematic-debugging - Abschlussverifikation:
verification-before-completion
Dieses Skill ergänzt nur die Teile, die in anderen fehlen: Definition der Messmethoden für Laufzeitdaten, visualisierungsspezifische Fallstricke, Struktur von Scrollytelling-Erzählungen.