ruinosus/chalk-talk

chalk-talk: erklären durch Zeichnen

Du erstellst eine handgezeichnete Erklärung: ein Rezept in einem kurzen Text (.chalk), das der Player in diesem Skill Strich für Strich zeichnet, mit Kapiteln, einer kurzen Erzählung und, wenn es eine reale Größe gibt, einem Wert, den die Person verschieben kann. Du schreibst nur das Rezept; scripts/build.mjs prüft es und baut eine HTML-Datei mit allem darin. Schreibe oder kopiere niemals den Player selbst. Die Pfade unten beziehen sich auf den Ordner dieses Skills.

1. Zeichne zuerst

Bei einer normalen Anfrage („Erkläre X durch Zeichnen“, „Zeichne wie Y funktioniert“) frage nicht und zeige keine Gliederung: zeichne. Entscheide selbst die drei Dinge, die eine Zeichnung braucht, und nenne sie bei der Auslieferung:

• der Aufhänger: ein Ding aus dem Alltag, mit dem die Idee verknüpft ist, das das Publikum gesehen oder getan hat und das mit wenigen Formen gezeichnet werden kann (eine Kreditkartenabrechnung, eine Bushaltestelle, eine Caféschlange);
• für wen es ist: was die Anfrage sagt, sonst ein neugieriger Erwachsener;
• der Wert, den die Person verschiebt: eine reale Größe in der Idee (der monatliche Zinssatz, die Leute pro Minute), oder keinen.

Eine Zeichnung zum Präsentieren, Überzeugen, Entscheiden, Dokumentieren oder um zu erzählen, was passiert ist (ein Pitch, eine Architektur für einen Kunden, eine Post-Mortem-Analyse) ist Sache von Back-of-Napkin, wenn es installiert ist; dieser Skill lehrt.

Frage zuerst – einmal, alles zusammen, und nur, was fehlt –, wenn es für eine Klasse, Studenten, einen Vortrag oder einen Kurs ist (siehe „Für eine Klasse“), wenn die Anfrage zwei verschiedene Dinge bedeuten könnte, oder wenn die Person darum bittet, zuerst den Plan zu sehen.

Die Zeichnung hat vier Teile, jeweils ein Kapitel: der Aufhänger als Frage („Warum werden aus R$ 1.000 R$ 1.974?“); nimm es auseinander (das reale Ding, einfach, und was darin verborgen ist); die Idee (die Regel, der Ablauf oder das Argument, mit dem Wert, der sich bewegt); der Abschluss (ein Hervorheben des Ergebnisses und wo der Vergleich aufhört).

2. Schreibe das Rezept

Schreibe <id>.chalk mit den Zeilen unten – das deckt die übliche Zeichnung ab; du musst nichts anderes zuerst lesen. Das Papier ist 900 × 560 (size 900x780 macht eine höhere Tafel), x wächst nach rechts und y nach unten, der at-Punkt einer Figur ist ihr Standort (ihre untere Mitte); halte 30 px Abstand zu den Rändern. # Titel öffnet ein Kapitel und > Satz ist die Erzählung: beide gehen zum nächsten Schritt. Ein Punkt ist x,y ohne Leerzeichen; ein Ausdruck steht in Anführungszeichen und kann die Parameter und Variablen verwenden.

Es ist eine Tafel: Ein Kapitel löscht niemals das Papier. Alles Gezeichnete bleibt, wie Kreide auf einer Tafel, also plane die ganze Tafel, bevor du schreibst, und gib jedem Teil seinen eigenen Platz – den Titel einmal oben, den Aufhänger und das reale Ding in der oberen Hälfte, die Idee darunter oder daneben, den Abschluss im verbleibenden Platz. Zeichne niemals zwei Dinge an dieselbe Stelle; 12 bis 25 Schritte sind normalerweise ausreichend.

Der Anfang:

title Juros compostos ↔ a fatura do cartão
locale pt-BR
size 900x560
param taxa "juros ao mês (%)" 1..15 step=1 = 8
switch atraso "pagar com atraso" off
var f = "1 + taxa/100"
learning goal "Ver o juro sobre o juro crescer mês a mês."

Schreibe alle vier learning-Zeilen – goal, question (zum Nachdenken), answer (fundiert) und caveat (was vereinfacht wurde) – und setze locale auf die Sprache der Person, mit jedem Text darin.

Personen und Dinge sind Figuren: person, person-sitting, person-pointing, house, car, bus, coin, phone, document, server, bank, cloud, queue, desk, computer, clock, lock, money-arrow, tree, school, hospital, factory, truck, cart, safe, bulb, gear, database, robot, ship, container, warehouse, box, pallet, shop, shelf, field, cup, function, api-gateway, cache, cluster, board, book, pencil. Eine Person nimmt mood= happy, sad, surprised, worried oder idea.

person ana at 150,330 "Ana" mood=worried
text "R$ 1.000 viram quanto?" at 40,64 size=36
text "paga só o mínimo" right-of ana gap 16 align=start
ana thinks "e se eu atrasar?" side=above width=200
ana -> banco "paga" -> loja "repassa"
arrow 60,350 -> 840,350 color=#2E8F62 stroke=3
highlight 90,500 -> 810,500 thickness=24

Platzieren ohne Koordinaten auszurechnen – bevorzuge diese, wenn Teile nebeneinander sitzen oder einander folgen. Eine chain sind Dinge, die etwas weitergeben: über das Papier verteilt, jedes mit dem nächsten verbunden, mit den langen Pfeilen, wenn gewünscht:

chain at 40,190 forward="o café desce" back="pedidos sobem"
  field fazenda "fazenda"
  truck caminhao "transporte"
  cup cafe "cafeteria"
  person voce "você"
row at 470,150 gap 14
  repeat 3: coin size 44
repeat 3: coin at "100 + i*60",400 size 40

Etwas, das sich ab diesem Schritt an Ort und Stelle weiterbewegt – spin, drive, steam (Dampf darüber), talk, pulse oder float, und stop. Nur wo die Bewegung etwas aussagt (der LKW fährt los, Dampf über der Tasse), ein oder zwei pro Zeichnung:

animate caminhao drive

Ein vorgefertigtes animiertes Emoji – nur wenn die Person danach fragt, und höchstens eines pro Lektion (es ist poliert, nicht Kreide): celebrate, think, surprised, ok, idea oder time, zentriert bei at; oder ./file.json, eine Lottie-Datei, die die Person gegeben hat, neben dem Rezept. Der Build packt sie in die Datei, mit ihrer Quellenangabe – und die Datei wächst von etwa 340 KB auf etwa 610 KB (der Player und die Animation):

lottie celebrate at 720,180 size=120

Zahlen, die dem Wert folgen:

counter at 470,270 "1000*f^6" "R$ {v:0} em seis meses" size=34
bars box 90,320,440,180 values 1000,"1000*f^3","1000*f^6" labels hoje,"3 meses","6 meses" format="R$ {v:0}"
plot "1000*(1+taxa/100)^x" domain 0..12 range 0..4000 box 480,120,360,240
when atraso:
  text "multa de 2%" at 600,100 color=#C8442C

Ein Ding, das keine Figur zeichnet: Erstelle es auf einem 0–100 Raster (ganze Zahlen, y nach unten; es steht bei 50,100), dann verwende seinen Namen:

define xicara
  polygon 24,48 76,48 70,90 30,90 fill=#FFFFFF
  curve 74,56 90,62 72,80
xicara minha at 450,300 "minha xícara"

Warten auf die Person und ein Quiz (beides für eine Klasse):

pause ask "Quanto vai virar a fatura em seis meses?"
quiz "Se a taxa dobra, a fatura em seis meses…"
  * mais que dobra o juro -- é juro sobre juro
  - só dobra -- isso seria juro simples

Behalte bei: 8 bis 40 Schritte auf einer Tafel; eine kurze Erzählung nur, wenn sich die Idee ändert; Titel 36 bis 44, Beschriftungen 24 bis 34, nichts unter 22; Farben Graphit (Voreinstellung), #2F5BEA, #C8442C, #2E8F62, #8C8578, Marker #FFE45C, höchstens drei Akzente; Fakten und Zahlen richtig – erfinde niemals ein Zitat oder eine Zahl. Andere Schritte (Kreis, Kurve, Karte, Tabelle, Achse, Zeitstrahl, geschweifte Klammer, Notiz, Bewegung…) stehen in references/text.md; was jeder zeichnet, in references/recipe.md. Öffne sie nur, wenn du einen Schritt brauchst, der nicht oben steht, oder die Build-Meldung einen Fehler nicht behebt.

Wenn die Person ein Mermaid-Diagramm angibt, behalte es bei, füge %% title …, %% # Kapitel und %% > Erzählung-Zeilen hinzu und speichere es als <id>.mmd (references/text.md zeigt wie). Speichere das Rezept in dem Ordner, in dem die Person arbeitet, oder, wenn ein Ausgabeordner für herunterladbare Dateien existiert (auf claude.ai /mnt/user-data/outputs), dort.

3. Bauen und prüfen

node scripts/build.mjs <id>.chalk

Es schreibt <id>.html neben das Rezept und gibt aus:

• ✗ text: Zeile N … oder ✗ contract: … (exit 1, nichts geschrieben): Korrigiere diese Zeile so, wie die Meldung es sagt, wie das Beispiel darunter zeigt.
• ! review … (exit 3): gezeichnet, aber etwas verlässt das Papier, ein Text überdeckt einen anderen oder eine Linie kreuzt einen Text. Korrigiere es und baue erneut mit --snapshots: es schreibt auch <id>.snapshots/<id>.contact-sheet.png – jedes Kapitel bei jeder Einstellung der Werte. Öffne dieses Bild und korrigiere, was die Überprüfung genannt hat, und alles, was nicht richtig lesbar ist (eine nicht erkennbare Figur, eine überfüllte Ecke, ein zu kleiner Text).
• ✓ review, oder • review … die Seite prüft sich selbst beim Öffnen (kein Browser hier): fertig.
• • figures … defined: Das Rezept erstellt eine Figur mit define, und die Überprüfung misst nur sie – öffne das Kontaktblatt einmal und prüfe, ob die Figur als das Ding lesbar ist, das sie sein soll.
• ✗ review not checked: …: fertig, aber sage der Person, dass die Zeichnung nicht geprüft wurde.

Höchstens zwei Runden Korrekturen; dann liefere aus und sage in einfachen Worten, was übrig ist („bei 15 % berührt die Beschriftung den Titel“).

Mehrere Lektionen (ein Kurs): ein Rezept pro Lektion, gemeinsam gebaut – node scripts/build.mjs eins.chalk zwei.chalk --out kurs.html --title "Der Kurs". Für eine README (oder wo nur ein Bild hin soll), wenn gewünscht: node scripts/build.mjs <id>.chalk --svg schreibt <id>.svg, ein Bild, das sich selbst zeichnet; die Lektion ist immer noch das .html.

4. Ausliefern

Gib den Pfad des .html (oder die Datei selbst, wo die Person Dateien herunterlädt) und in einer Zeile was du gewählt hast und ein Angebot, es zu ändern: „Ich habe es an eine Kreditkartenabrechnung geknüpft, für jemanden, der nie Zinsen gelernt hat, mit dem monatlichen Zinssatz zum Verschieben – möchtest du einen anderen Aufhänger, ein anderes Publikum oder etwas geändert haben?“ Dann ein Satz, worauf man achten soll („Drücke Weiter; in Kapitel 3 verschiebe den Zinssatz“). Die Datei öffnet offline, mit Kapiteln, den Werten neben dem Papier und PNG-, SVG-, GIF- und WebM-Download – sie kann per E-Mail verschickt oder auf einem Beamer gezeigt werden.

Zum Präsentieren (ein Vortrag, eine Klasse am Beamer): baue mit --present – die Seite öffnet ein Kapitel nach dem anderen, im Vollbild und die Sprechernotizen mit dem ersten Schlüssel; ein Klicker mit PageDown bewegt weiter. Ein PowerPoint, wenn gewünscht: --pptx (eine Folie pro Kapitel; steps lässt die Zeichnung Klick für Klick wachsen, video bettet jedes Kapitel ein, das sich selbst zeichnet), mit der Erzählung als Sprechernotizen.

Für eine Klasse

Wenn die Zeichnung für eine Klasse, Studenten, einen Vortrag oder einen Kurs ist, frage zuerst, in einer Nachricht: bis zu drei Aufhänger, den besten zuerst, jeder mit einer Zeile, warum er für dieses Publikum funktioniert (references/hooks.md), für wen genau es ist und welche Zahl die Studenten verschieben könnten. Frage niemals nach dem, was bereits gesagt wurde. Zeige dann die vierteilige Gliederung in wenigen Zeilen und warte auf das Go („pode“, „los“). Das Rezept fügt theme chalkboard, eine pause ask, die den Teil öffnet, der sie beantwortet, und ein quiz am Ende hinzu.

Keine Codeausführung (ein Artefakt stattdessen)

Wo du keinen Code ausführen, aber ein HTML-Artefakt zeigen kannst, setze das Rezept in diese kleine Seite – nichts anderes – und zeige sie. Der Player lädt vom CDN und prüft das Rezept selbst:

<!doctype html>
<meta charset="utf-8">
<title>LEKTIONSTITEL</title>
<script type="text/chalk-talk" id="chalk-recipe">
DAS REZEPT ALS TEXT
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>

Wenn die Seite sagt, dass das Rezept nicht geöffnet werden konnte, korrigiere die genannte Zeile.

Später ändern

„Mach den Pfeil blau“, „füge eine zweite Person hinzu“, „verwende stattdessen 5 %“: ändere nur, wonach gefragt wurde, behalte den Rest, baue erneut und sage, was sich geändert hat. Ein anderer Aufhänger oder ein anderes Publikum ist eine neue Zeichnung.

Niemals

• Bearbeite niemals assets/ oder scripts/contract.mjs: sie werden generiert.
• Setze niemals HTML, Links, Skripte oder Bilder in ein Rezept: Texte sind Klartext, Farben sind Hex oder Namen.
• Schreibe niemals ein Skript, um das Rezept zu generieren: schreibe es selbst (Ausdrücke und repeat erledigen die Arithmetik).
• Ohne Codeausführung schreibe niemals den Player, ein SVG oder ein Bild der Zeichnung von Hand: verwende die kleine Seite oben. Wenn du weder Code ausführen noch ein Artefakt zeigen kannst, sage das und gib das Rezept.