ruinosus/chalk-talk

chalk-talk: explicar dibujando

Haces una explicación dibujada a mano: una receta en un texto corto (.chalk) que el reproductor de esta habilidad dibuja trazo a trazo, con capítulos, una narración breve y, cuando hay una cantidad real, un valor que la persona mueve. Escribes solamente la receta; scripts/build.mjs la verifica y construye un único archivo HTML con todo incluido. Nunca escribas o copies el reproductor tú mismo. Las rutas a continuación son relativas a la carpeta de esta habilidad.

1. Dibujar primero

Para una solicitud común ("explica X dibujando", "dibuja cómo funciona Y") no preguntes ni muestres un esquema: dibuja. Decide tú mismo las tres cosas que necesita un dibujo, y diles cuando entregues:

• el gancho: algo de la vida cotidiana a lo que se vincula la idea, que la audiencia haya visto o hecho y que se pueda dibujar con pocas formas (una factura de tarjeta, una parada de autobús, una cola en un café);
• para quién es: lo que diga la solicitud, si no, un adulto curioso;
• el valor que la persona mueve: una cantidad real de la idea (la tasa mensual, personas que llegan por minuto), o ninguno.

Un dibujo para presentar, convencer, decidir, documentar o contar lo que pasó (un pitch, una arquitectura para un cliente, un post-mortem) es de back-of-napkin, cuando está instalado; esta habilidad enseña.

Pregunta primero — una sola vez, todo junto, y solo lo que falta — cuando es para una clase, estudiantes, una charla o un curso (ver «Para una clase»), cuando la solicitud podría significar dos cosas diferentes, o cuando la persona pide ver el plan primero.

El dibujo tiene cuatro partes, un capítulo cada una: el gancho como pregunta ("¿por qué R$ 1.000 se convierten en R$ 1.974?"); desglosarlo (la cosa real, simplemente, y lo que está oculto en ella); la idea (la regla, el flujo o el argumento, con el valor que se mueve); el cierre (un destaque del resultado y dónde termina la comparación).

2. Escribir la receta

Escribe <id>.chalk con las líneas siguientes — esto cubre el dibujo habitual; no necesitas leer nada más primero. El papel es de 900 × 560 (size 900x780 hace una pizarra más alta), x crece hacia la derecha e y hacia abajo, la posición at de un accesorio es donde se apoya (su centro inferior); mantén 30 px de los bordes. # Título abre un capítulo y > oración es la narración: ambos van al siguiente paso. Un punto es x,y sin espacio; una expresión va entre comillas y puede usar los parámetros y variables.

Es una sola pizarra: un capítulo nunca limpia el papel. Todo lo dibujado permanece, como tiza en un pizarrón, así que planifica la pizarra completa antes de escribir y dale a cada parte su propio lugar — el título una vez arriba, el gancho y la cosa real en la mitad superior, la idea debajo o al lado, el cierre en lo que quede. Nunca dibujes dos cosas en el mismo lugar; 12 a 25 pasos suelen ser suficientes.

La parte superior:

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 con atraso" off
var f = "1 + taxa/100"
learning goal "Ver el interés sobre el interés crecer mes a mes."

Escribe las cuatro líneas learning — goal, question (una para pensar), answer (concreta) y caveat (lo que se simplificó) — y establece locale al idioma de la persona, con todos los textos en ese idioma.

Las personas y cosas son accesorios: 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. Una persona acepta mood= happy, sad, surprised, worried o idea.

person ana at 150,330 "Ana" mood=worried
text "R$ 1.000 viram quanto?" at 40,64 size=36
text "paga solo el mínimo" right-of ana gap 16 align=start
ana thinks "¿y si me atraso?" 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

Colocar sin calcular coordenadas — prefiere estos cuando las piezas están una al lado de la otra o se siguen. Un chain son cosas que se pasan algo entre sí: esparcidas sobre el papel, cada una unida a la siguiente, con flechas largas si se pide:

chain at 40,190 forward="el café baja" back="pedidos suben"
  field fazenda "finca"
  truck caminhao "transporte"
  cup cafe "cafetería"
  person voce "tú"
row at 470,150 gap 14
  repeat 3: coin size 44
repeat 3: coin at "100 + i*60",400 size 40

Algo que sigue moviéndose en su lugar, a partir de ese paso — spin, drive, steam (vapor sobre él), talk, pulse o float, y stop. Solo donde el movimiento dice algo (el camión se va, vapor sobre la taza), uno o dos por dibujo:

animate caminhao drive

Un emoji animado ya preparado — solo cuando la persona lo pide, y como máximo uno por lección (es pulido, no tiza): celebrate, think, surprised, ok, idea o time, centrado en at; o ./file.json, un archivo Lottie que la persona dio, junto a la receta. La compilación lo coloca dentro del archivo, con su crédito — y el archivo crece de unos 340 KB a unos 610 KB (el reproductor y la animación):

lottie celebrate at 720,180 size=120

Números que siguen el valor:

counter at 470,270 "1000*f^6" "R$ {v:0} en seis meses" size=34
bars box 90,320,440,180 values 1000,"1000*f^3","1000*f^6" labels hoy,"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

Una cosa que ningún accesorio dibuja: créala en una cuadrícula 0–100 (números enteros, y hacia abajo; se apoya en 50,100), luego usa su nombre:

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 "mi xícara"

Esperar a la persona, y un cuestionario (ambos para una clase):

pause ask "¿Cuánto será la factura en seis meses?"
quiz "Si la tasa se duplica, la factura en seis meses…"
  * más que duplica el interés -- es interés sobre interés
  - solo duplica -- eso sería interés simple

Mantén: de 8 a 40 pasos en una pizarra; narración breve solo cuando cambia la idea; títulos de 36 a 44, etiquetas de 24 a 34, nada menor de 22; colores grafito (el predeterminado), #2F5BEA, #C8442C, #2E8F62, #8C8578, marcador #FFE45C, tres acentos como máximo; hechos y números correctos — nunca inventes una cita o una cifra. Otros pasos (circle, curve, card, table, axis, timeline, brace, note, move…) están en references/text.md; lo que dibuja cada uno, en references/recipe.md. Ábrelos solo cuando necesites un paso que no esté arriba o el mensaje de compilación no resuelva un error.

Si la persona da un diagrama Mermaid, mantenlo como está, agrega líneas %% title …, %% # capítulo y %% > narración y guárdalo como <id>.mmd (references/text.md muestra cómo). Guarda la receta en la carpeta donde trabaja la persona, o, cuando exista una carpeta de salidas para archivos que la persona descarga (en claude.ai, /mnt/user-data/outputs), allí.

3. Compilar y verificar

node scripts/build.mjs <id>.chalk

Esto escribe <id>.html junto a la receta e imprime:

• ✗ text: line N … o ✗ contract: … (exit 1, no se escribió nada): corrige esa línea como indica el mensaje, tal como muestra el ejemplo debajo.
• ! review … (exit 3): dibujado, pero algo sale del papel, un texto cubre otro o una línea cruza un texto. Arrégialo y compila de nuevo con --snapshots: también escribe <id>.snapshots/<id>.contact-sheet.png — cada capítulo en cada configuración de los valores. Abre esa imagen y corrige lo que nombró la revisión y cualquier cosa que no se lea bien (una figura que no se reconoce, una esquina abarrotada, un texto demasiado pequeño).
• ✓ review, o • review … la página se verifica sola al abrirse (sin navegador aquí): listo.
• • figures … defined: la receta crea una figura con define, y la revisión solo la mide — abre la hoja de contactos una vez y verifica que la figura se lea como lo que debería ser.
• ✗ review not checked: …: listo, pero dile a la persona que el dibujo no fue verificado.

Como máximo dos rondas de correcciones; luego entrega y di en palabras simples qué queda ("con el 15 % la etiqueta toca el título").

Varias lecciones (un curso): una receta cada una, compiladas juntas — node scripts/build.mjs one.chalk two.chalk --out course.html --title "El curso". Para un README (o donde solo va una imagen), cuando se pida: node scripts/build.mjs <id>.chalk --svg escribe <id>.svg, una imagen que se dibuja sola; la lección sigue siendo el .html.

4. Entregar

Da la ruta del .html (o el archivo mismo donde la persona descarga archivos) y, en una línea, lo que elegiste y una oferta para cambiarlo: "Lo vinculé a una factura de tarjeta de crédito, para alguien que nunca estudió interés, con la tasa mensual para mover — ¿quieres otro gancho, otra audiencia o algo cambiado?" Luego una frase sobre qué mirar ("Presiona Siguiente; en el capítulo 3, mueve la tasa"). El archivo se abre sin conexión, con capítulos, los valores al lado del papel, y descarga en PNG, SVG, GIF y WebM — se puede enviar por correo electrónico o en un proyector.

Para presentarlo (una charla, una clase en un proyector): compila con --present — la página se abre en un capítulo a la vez, pantalla completa y las notas del orador con la primera tecla; el AvPág de un clicker avanza. Un PowerPoint, cuando se pida: --pptx (una diapositiva por capítulo; steps hace crecer el dibujo clic a clic, video incrusta cada capítulo dibujándose), con la narración como notas del orador.

Para una clase

Cuando el dibujo es para una clase, estudiantes, una charla o un curso, pregunta primero, en un solo mensaje: hasta tres ganchos, el mejor primero, cada uno con una línea sobre por qué funciona para esa audiencia (references/hooks.md), quién exactamente es y qué número podrían mover los estudiantes. Nunca preguntes lo que ya se dijo. Luego muestra el esquema de cuatro partes en unas pocas líneas y espera la confirmación ("pode", "vamos"). La receta añade theme chalkboard, un pause ask que abre la parte que responde, y un quiz al final.

Sin ejecución de código (un artefacto en su lugar)

Cuando no puedas ejecutar código pero puedas mostrar un artefacto HTML, coloca la receta en esta página pequeña — nada más — y muéstrala. El reproductor carga desde el CDN y verifica la receta por sí mismo:

<!doctype html>
<meta charset="utf-8">
<title>TÍTULO DE LA LECCIÓN</title>
<script type="text/chalk-talk" id="chalk-recipe">
LA RECETA COMO TEXTO
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>

Si la página dice que la receta no se pudo abrir, corrige la línea que nombra.

Cambiarlo después

"Haz la flecha azul", "agrega una segunda persona", "usa 5 % en su lugar": cambia solo lo que se pidió, mantén el resto, compila de nuevo y di qué cambió. Un gancho o audiencia diferente es un dibujo nuevo.

Nunca

• Nunca edites assets/ o scripts/contract.mjs: son generados.
• Nunca pongas HTML, enlaces, scripts o imágenes en una receta: los textos son texto plano, los colores son hex o nombres.
• Nunca escribas un script para generar la receta: escríbela tú mismo (las expresiones y repeat hacen la aritmética).
• Sin ejecución de código, nunca escribas a mano el reproductor, un SVG o una imagen del dibujo: usa la página pequeña de arriba. Si no puedes ni ejecutar código ni mostrar un artefacto, dilo y da la receta.