KehanLiu/anim-slides

Was macht anim-slides?

Animierte SVG-Illustrationen für Foliensätze, erstellt aus vorhandenen Folien oder aus Dokumentation. Die Ausgabe ist immer ein Fragment: eine HTML-Datei mit einem <style>- und einem <svg>-Element, keine Skripte, keine externen Dateien, thematisiert durch CSS-Variablen, das in jeden Foliensatz integriert werden kann. references/fragment-contract.md ist der Vertrag. Lies ihn, bevor du etwas baust.

Wann verwenden

• Eine Folie besteht aus einer Reihe von Textkarten, einer Aufzählungsliste oder einem Screenshot, und der Inhalt ist ein Prozess, ein Ablauf, eine Abhängigkeitsstruktur, ein Zeitstrahl, ein Vergleich, eine Architektur oder eine Zeitreihe.
• Ein Dokument (Markdown, Confluence-Export, README, Mermaid-Block) beschreibt einen Prozess oder Abhängigkeiten, und der Benutzer möchte es als Animation auf einer Folie oder Seite dargestellt sehen.
• Der Host ist ein HTML-Foliensatz (frontend-slides, reveal.js, impress.js, Slidev, handgeschrieben) oder eine einfache Webseite. Eine .pptx- oder Markdown-Quelle wird zuerst durch einen Deck-Skill (Schritt 0) in einen gestalteten HTML-Foliensatz konvertiert; dieser Skill fügt dann die Illustrationen hinzu.

Arbeitsablauf

<skill-dir> unten ist der Ordner, der diese SKILL.md enthält (Claude Code stellt es als $CLAUDE_SKILL_DIR zur Verfügung; in anderen Umgebungen verwende den Pfad, von dem du diese Datei geladen hast). Skripte benötigen Python 3.9+ und zum Rendern ein Chrome- oder Chromium-Binary. anim/<name>/ ist ein Ordner neben dem Foliensatz des Benutzers.

0. Aufnahme

Besorge zuerst einen HTML-Foliensatz. anim-slides fügt Figuren zu einem HTML-Foliensatz hinzu; es entwirft keinen.

• Die Quelle ist bereits ein HTML-Foliensatz (reveal.js, impress.js, jedes <section>- oder .slide-Deck): fortfahren.
• Die Quelle ist eine .pptx, Markdown, remark, ein Dokument oder etwas anderes, das kein HTML-Foliensatz ist: Ein Deck-Skill erstellt zuerst den HTML-Foliensatz, nicht anim-slides. In der Reihenfolge der Präferenz: (a) der eigene oder der Deck-Skill der Organisation des Benutzers, falls installiert; (b) frontend-slides, falls installiert (es konvertiert pptx und Markdown in einen gestalteten HTML-Foliensatz; wenn es ästhetische Vorschauen anbietet, wähle diejenige, die dem Marke der Quellfolie am nächsten kommt, es sei denn, der Benutzer wünscht ein neues Aussehen); (c) nur wenn kein Deck-Skill installiert ist, scripts/md_to_deck.py als Fallback (siehe den Fallback-Punkt unten) und teile dem Benutzer in einem Satz mit, dass die Ausgabe ein schlichter Host und kein Design ist und sich wie ein Dokument liest, bis ein Deck-Skill oder Designer es gestaltet. In den Fällen (a) und (b) bleibt die ursprüngliche .pptx die Quelle für die Triage von extract_slides.py und render_deck.py (Diagramme, Abbildungen, Notizen), aber die Integration zielt auf das vom Skill erstellte Deck, und das angepasste Erscheinungsbild stammt von dessen Palette über host_theme.py. Frage den Deck-Skill (oder mache es direkt danach), den Körper jeder Kandidatenfolie in einen Slot mit fester Größe <div id="sN-slot"> zwischen <!-- sN-body --> und <!-- /sN-body --> zu packen (die ID- und Markernamen, die md_to_deck.py verwendet, obwohl der Slot dort ein leeres Geschwister des Körpers ist): measure_slot.py --selector '#sN-slot' ist dann exakt, und integrate_fragment.py --anchor/--replace-until zielt auf die Marker. Der eigene Font-Link eines Deck-Skills (Google Fonts, Fontshare) ist die Last des Decks, nicht eine von anim-slides hinzugefügte; behalte ihn und binde ihn bei der Übergabe mit bundle_deck.py --fetch ein.

Entscheide dann, welcher Einstiegspunkt zutrifft:

• Vorhandenes Deck: Führe python3 <skill-dir>/scripts/extract_slides.py deck.pptx|deck.html|doc.md -o anim/outline.json und python3 <skill-dir>/scripts/render_deck.py deck -o anim/render aus, sieh dir dann die sheet-NN.png-Kontaktabzüge (12 nummerierte Folien pro Blatt) an, nicht Seite für Seite (wenn die Anzahl der Bilder einer Folie in outline.json von den Bildern in ihrem Render abweicht, überprüfe die Bilder des Folienlayouts: ein Titelbild auf dem Layout ist leicht zu übersehen); führe dann die Triage mit references/input-stage.md durch und schreibe die Tabelle nach anim/triage.md: Jede Folie, eine Entscheidung und ein Grund, kein stillschweigendes Überspringen (3 bis 8 Illustrationen pro 30 Folien ist normal; bei einem kurzen Deck erhält jede Prozess-, Struktur-, Zeitstrahl-, Vergleichs- oder Datenfolie eine). Lege dann das Aussehen einmal für das gesamte Deck fest: match (Fragmente übernehmen die Palette und Schriftarten des Hosts, der Standard für Marken- oder Unternehmensdecks) oder lean (Fragmente behalten die schlanke Palette auf dunklem Grund, für Vorträge und Pitches). python3 <skill-dir>/scripts/host_theme.py deck.html --mode match -o anim/host-theme.css leitet den Match-Kleber aus dem CSS des Decks ab (--mode lean schreibt den Lean-Kleber); vergleiche den abgeleiteten Block einmal mit den eigenen Variablen des Decks (eine gedämpfte Textfarbe, ein sekundärer Hintergrund) und korrigiere von Hand, wo die Ableitung eine berechnete Mischung gewählt hat; rendere das erste Fragment auf beide Arten (render-phases.sh --theme anim/host-theme.css ...) und zeige die beiden Standbilder, bevor der Rest gebaut wird, es sei denn, der Benutzer hat bereits ein Aussehen genannt. Zwischen den beiden Modi ändern sich nur Farben und Schriftarten: Die Formregeln von references/style.md gelten in beiden. Die Steuerung ist once für das gesamte Deck, es sei denn, der Benutzer wünscht eine Klick-Steuerung: Die Figur jeder Folie spielt einen ruhigen Durchlauf ab, wenn die Folie erscheint, und ruht dann. Empfehle step nicht von selbst. Erwähne es nur in einer Zeile, wenn outline.json builds über 0 meldet (die Quelle baut bereits durch Klick: reveal.js-Fragmente, PowerPoint-Klickanimationen, impress.js-Unterphasen, die eigenen Build-Schritte des Decks): „Ihr Deck baut per Klick auf; die Figuren können dasselbe tun (step), sagen Sie es, wenn Sie es möchten.“ Unter step zeichnet der Eintritt auf und jeder Klick landent die nächste Phase; die Phasen sind die erzählten Phasen des Briefings (3 bis 5 pro Folie), die Fragmentdatei ist dieselbe, und der Klick reitet auf der eigenen Navigation des Decks. Step hört nur auf Tasten, daher wird ein Step-Deck mit der Tastatur oder einem Klicker präsentiert (ein Deck, das auch per Rad oder Wisch navigiert, wie frontend-slides, überspringt die Phasen beim Scrollen). Schreibe Look und Control in den Header von anim/triage.md.
• Fallback, kein Deck-Skill installiert (Markdown, remark oder eine zu Markdown extrahierte pptx) : python3 <skill-dir>/scripts/md_to_deck.py deck.md -o deck.html erstellt einen einfachen, eigenständigen Host zur Integration (ein <section> pro Folie, .visible-Gatter, Drucklayout, <!-- sN-body -->-Marker um den Körper jeder Folie). Es ist kein gestaltetes Deck: Sage dies dem Benutzer in einem Satz. Rufe zuerst die Bilder ab, auf die das Markdown verweist (relative Pfade), in denselben Ordner, sonst zeigt das Deck Platzhalter; extrahiere dann aus der ursprünglichen Quelle (der .pptx, falls vorhanden) oder dem Markdown.
• Dokumentation: Lies die Quelle, wähle den Archetyp mit der Tabelle in references/archetypes.md, extrahiere eine Spezifikation (Schritt 1).
• Einzelfolien-Anfrage: Gehe direkt zu Schritt 1 für diese Folie. Frage den Benutzer nur, wenn die Quelle in Bezug auf Reihenfolge, Richtung oder Gruppierung mehrdeutig ist. Gib sonst die Annahme im Briefing an und fahre fort.

1. Spezifikation

Schreibe anim/<name>/spec.yaml gemäß references/spec-format.md: Name, Archetyp, Knoten, Kanten, Gruppen, Phasen mit Sekundenmarken, Zyklus (die Durchlauflänge), Steuerung (die Wahl des Decks aus der Aufnahme: once, ein ruhiger Durchlauf von 4 bis 10 s, wenn die Folie aktuell wird, endend auf dem Ruhebild; step, derselbe Durchlauf, abgeschnitten an den Phasenmarken, sodass jeder Klick die nächste Phase landet; loop nur, wenn der Benutzer eine Endlosschleife anfordert). Die Fragmentdatei ist dieselbe unter once und step; die Phasenmarken werden zu data-anim-phases. Verwende die eigenen Wörter der Quelle als Beschriftungen. Halte eine Spezifikation unter etwa 12 Knoten; teile sie andernfalls auf.

1b. Überprüfe den Pool

Lies <skill-dir>/pool/index.yaml, dann $ANIM_POOL/index.yaml (oder liste $ANIM_POOL/*/ auf), falls diese Variable gesetzt ist, und suche nach einem Eintrag mit demselben Archetyp und einer ähnlichen Geschichte oder Tags.

• Nahe Übereinstimmung: Kopiere den Ordner nach anim/<name>/, benenne das Fragment und jedes Präfix in <name> um, passe dann Beschriftungen, Daten, Timing und viewBox an die Spezifikation in Schritt 3 an, anstatt zu gerüsten. Seine spec.yaml, falls vorhanden, ist ein Ausgangspunkt für deine.
• Nur gleicher Archetyp: Gerüste wie gewohnt und öffne das Pool-Fragment als Qualitätsmaßstab für Dichte, Bewegung und Ruhebild.
• Nichts passt: Baue aus der Spezifikation; der nächste Pool-Eintrag ist dennoch einen Blick wert. Kopiere niemals ein Pool-Fragment unverändert in ein Deck: Seine Geschichte ist ein Beispiel, nicht die des Benutzers.

2. Slot und Briefing

Miss die freie Box auf der Folie: python3 <skill-dir>/scripts/measure_slot.py deck.html --slide N [--selector SEL] [--ignore .body] gibt die Box in Bildschirmpixeln aus, eine passende viewBox und die Prüferflags (references/layouts.md erklärt den manuellen Weg). Bei einem absolut positionierten Layout liefert die Messung ohne --selector Müll; miss den Slot-Div (--selector '#sN-slot', Schritt 0). Wähle eine viewBox mit demselben Seitenverhältnis und fülle anim/<name>/brief.md aus references/brief-template.md. Das Briefing legt viewBox und gerenderte Größe, Komposition, Phasen, Ruhebild, Themen-Tokens und minimale Textgröße fest und benennt, was auf der Folie das Fragment ersetzt (die Pillen, die Box-Diagramm, die Aufzählungsspalte). Die Qualität des Fragments richtet sich nach der Qualität des Briefings.

3. Bauen

python3 <skill-dir>/scripts/scaffold_from_spec.py anim/<name>/spec.yaml -o anim/<name>/<name>.html --rendered-width <px> validiert die Spezifikation und schreibt ein vertragskonformes Grundgerüst (Layout, Phasen, Pakete, Notizen, Ruhebild; Schriftgrößen auf den Mindestwert bei der gerenderten Breite angehoben), führt dann den Prüfer darauf aus. Der Kommentar am Anfang der Ausgabe listet auf, was von Hand verfeinert werden muss. Verfeinere es zu der Illustration, die das Briefing beschreibt, unter Verwendung von references/archetypes.md für Komposition und Bewegung, references/motion-rules.md für Timing und Easing und references/style.md für das Aussehen (lean: Ringe und dünne Linien, keine Boxen, ein glühender Akzent, Mono-Unterbeschriftungen, einfache Bildunterschriften). Baue bei mehreren Illustrationen jeweils ein Fragment aus den gemeinsamen Briefings, oder einen parallelen Unteragenten pro Fragment, falls die Umgebung diese hat; die Integration bleibt immer im Hauptthread.

4. Durch Ansehen verifizieren

1. python3 <skill-dir>/scripts/check_fragment.py anim/<name>/<name>.html --name <name> --rendered-width <px> --stage-width <Breite der Deck-Bühne> muss bestehen (Präfixe, Tokens, Gatter, Textgröße, verbotene Inhalte). --stage-width setzt die Textuntergrenze (18 px bei 1920, 12 px bei 1280); outline.json meldet die Bühne.
2. <skill-dir>/scripts/render-phases.sh anim/<name> <W> <H> 1.5 4 7 10 rest rendert Phasen-PNGs und ein Kontaktblatt mit der pausierten plus Negativverzögerungsmethode in einen temporären Ordner, den es ausgibt (übergib --out DIR, um zu wählen). Nach der Integration prüft render-phases.sh --page deck.html 1920 1080 rest das Ruhebild der Host-Seite; füge bei einer mehrseitigen Folie --slide N (oder #hash oder einen CSS-Selektor) hinzu. Verwende --no-script für zeitgesteuerte Mark- oder Phasenbilder, wenn das eigene Skript der Seite die Gatterklasse umschaltet, niemals für rest: In frontend-slides-Decks ist .visible sowohl das Gatter als auch die Klasse, die die Folie anzeigt, der Rest-Render entfernt sie, und die Folie bleibt nur stehen, weil das Skript des Decks auch .active setzt; ohne das Skript ist das Ruhebild leer. Öffne jedes PNG mit deinem Bildbetrachtungswerkzeug. Behebe Beschneidungen, Überlappungen, unleserlichen Text, leere Panels. Iteriere mindestens einmal.
3. Das Ruhebild muss als vollständiges Standbild lesbar sein (PDF-Export zeigt nur dieses).
4. python3 <skill-dir>/scripts/verify_facts.py anim/<name>/<name>.html --source anim/outline.json --slide <N> (oder --source doc.md) muss bestehen: Jede Zahl im Fragment stammt aus der Quelle oder ist als illustrativ markiert; lies jede WARNUNG und ersetze nicht nachvollziehbare Formulierungen durch die eigenen Wörter der Quelle oder entferne sie. Regeln in references/accuracy.md. Eine Abbildung ist erst fertig, wenn dieser Schritt bestanden ist. Vertraue niemals --virtual-time-budget und vertraue niemals darauf, die Quelle anstelle des PNG zu lesen.

5. Integrieren

python3 <skill-dir>/scripts/integrate_fragment.py deck.html anim/<name>/<name>.html --name <name> --anchor '<eindeutige Zeichenkette in der Folie>' [--replace-until '<zeichenkette>'] [--gate 'section.present'] [--control once|step] --backup bringt den Style in den Kopf, fügt das Fragment zwischen <!-- anim:<name>:start --> und <!-- anim:<name>:end -->-Markern ein (den Style zwischen anim-style-Markern; erneutes Ausführen ersetzt beide Kopien), schreibt das Gatter für das Host-Deck um und stellt jedem Klassennamen, der durchgerutscht ist, ein Präfix voran. Kopiere für einfache Seiten <skill-dir>/scripts/snippets/observer.html in die Seite. --control setzt die Deck-Steuerung auf dem Wrapper; --control step fügt auch scripts/snippets/step-host.html (ein kleines, einfaches Skript, keine Bibliothek) einmal in den Kopf ein und setzt sein Gatter von --gate. Die Steuerung ist ein Deck-weiter Schalter bei der Integration: Führe es mit dem anderen Wert erneut aus, um es zu ändern, die Fragmente bleiben wie sie sind. Die Anker- und die Bis-Zeichenkette bleiben erhalten; was dazwischen liegt, wird ersetzt. Das Gatter ist der Marker der Host-Folie für die aktuelle Folie: section.present für reveal.js, .visible für einfache Seiten (scripts/snippets/observer.html) und für Decks von md_to_deck.py. In md_to_deck.py-Decks und in Deck-Skill-Decks mit den Slot-Markern aus Schritt 0 ersetzt das Fragment den Körper: --anchor '<!-- sN-body -->' --replace-until '<!-- /sN-body -->'. Überprüfe, dass die Überschriften und der Textkörper der Folie ohne das Deck-Skript und im Druck sichtbar sind. Eingangsanimationen von Deck-Skills schalten ihre Einblendungen oft nur über die aktuelle-Folie-Klasse (frontend-slides zeigt .reveal-Elemente nur unter .slide.visible), daher zeigen Ruhe-Renderings und PDF leere Folien; schalte diese Einblendungen auch über die aktive Klasse des Decks (.slide.active) und füge eine Druckregel hinzu, die sie anzeigt. (Der Klassenname .reveal stimmt auch mit der reveal.js-Erkennung in host_theme.py's Folien-Selektoren überein; bisher harmlos, aber überprüfe, welche Folien es gefunden hat.) Es fügt auch eine Druckwache hinzu, sodass der PDF-Export (reveals ?print-pdf markiert jede Folie als vorhanden) die Ruhebilder anzeigt. Halte das Arbeitsdeck schlank : Fragmente sind kleiner SVG-Text und werden per Marker eingefügt, aber binde während der Arbeit keine Schriftarten, Bilder, Bibliotheken oder Stylesheets ein und lies niemals das gesamte Deck in den Kontext; lies Ausschnitte um den Anker herum (grep -n, sed -n) und lasse die Skripte es bearbeiten. Öffne dann das Deck in einem echten Browser und warte...

[gekürzt für die Übersetzung...]

6. Liefern

Übergebe die SQLite-Datenbank anim/slides.db mit der Tabelle slides und aktualisiere die Folienstandortdaten. Der Benutzer kann die Ergebnisse in wenigen Minuten überprüfen.

Referenzdokumente

• references/archetypes.md – Kompositions- und Bewegungsvorlagen
• references/accuracy.md – Faktenprüfungsregeln
• references/brief-template.md – Vorlage für das Briefing
• references/fragment-contract.md – Vertrag für Fragmente
• references/input-stage.md – Entscheidungsfindung für die Eingabe
• references/layouts.md – Anleitung für manuelle Layout-Messungen
• references/motion-rules.md – Timing- und Easing-Regeln
• references/spec-format.md – Format der YAML-Spezifikation
• references/style.md – Visuelle Stilregeln