chalk-talk: explique desenhando

O que chalk-talk: explique desenhando faz?

Você faz uma explicação desenhada à mão: uma receita em um texto curto (.chalk) que o player desta skill desenha traço por traço, com capítulos, uma narração curta e, quando há uma quantidade real, um valor que a pessoa move. Você escreve apenas a receita; scripts/build.mjs a verifica e constrói um único arquivo HTML com tudo dentro. Nunca escreva ou copie o player você mesmo. Os caminhos abaixo são relativos à pasta desta skill.

1. Desenhe primeiro

Para um pedido comum ("explique X desenhando", "desenhe como Y funciona") não pergunte e não mostre um esboço: desenhe. Decida você mesmo as três coisas que um desenho precisa e diga-as ao entregar:

• a âncora: uma coisa da vida cotidiana à qual a ideia está ligada, que o público já viu ou fez e que pode ser desenhada com poucas formas (uma conta de cartão, um ponto de ônibus, uma fila de café);
• para quem é: o que o pedido diz, senão um adulto curioso;
• o valor que a pessoa move: uma quantidade real na ideia (a taxa mensal, pessoas chegando por minuto), ou nenhum.

Um desenho para apresentar, convencer, decidir, documentar ou contar o que aconteceu (um pitch, uma arquitetura para um cliente, uma post-mortem) é do back-of-napkin, quando está instalado; esta skill ensina.

Pergunte primeiro — uma vez, tudo junto, e apenas o que estiver faltando — quando for para uma turma, alunos, uma palestra ou um curso (veja «Para uma turma»), quando o pedido puder significar duas coisas diferentes, ou quando a pessoa pedir para ver o plano primeiro.

O desenho tem quatro partes, um capítulo cada: a âncora como uma pergunta ("por que R$ 1.000 se tornam R$ 1.974?"); desmonte-a (a coisa real, simplesmente, e o que está escondido nela); a ideia (a regra, o fluxo ou o argumento, com o valor que se move); o fechamento (um destaque no resultado e onde a comparação para).

2. Escreva a receita

Escreva <id>.chalk com as linhas abaixo — isso cobre o desenho usual; você não precisa ler mais nada primeiro. O papel tem 900 × 560 (size 900x780 faz um quadro mais alto), x cresce para a direita e y para baixo, o at de um prop é onde ele fica (seu centro inferior); mantenha 30 px das bordas. # Título abre um capítulo e > frase é a narração: ambos vão para o próximo passo. Um ponto é x,y sem espaço; uma expressão vai entre aspas e pode usar os params e vars.

É um único quadro: um capítulo nunca limpa o papel. Tudo o que é desenhado permanece, como giz em um quadro-negro, então planeje todo o quadro antes de escrever e dê a cada parte seu próprio lugar — o título uma vez no topo, a âncora e a coisa real na metade superior, a ideia abaixo ou ao lado, o fechamento no que sobrar. Nunca desenhe duas coisas no mesmo lugar; 12 a 25 passos geralmente são suficientes.

O topo:

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."

Escreva todas as quatro linhas learning — goal, question (uma para pensar), answer (fundamentada) e caveat (o que foi simplificado) — e defina locale para o idioma da pessoa, com todo o texto nesse idioma.

Pessoas e coisas são props: 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. Uma pessoa aceita mood= happy, sad, surprised, worried ou 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

Posicionamento sem calcular coordenadas — prefira estes sempre que as peças ficarem lado a lado ou se seguirem. Uma chain é coisas que passam algo adiante: espalhadas pelo papel, cada uma ligada à próxima, com as setas longas se solicitado:

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

Algo que continua se movendo no lugar, a partir daquele passo — spin, drive, steam (vapor sobre ele), talk, pulse ou float, e stop. Apenas onde o movimento diz algo (o caminhão parte, vapor sobre a xícara), um ou dois por desenho:

animate caminhao drive

Um emoji animado pronto — apenas quando a pessoa pedir um, e no máximo um por lição (é polido, não giz): celebrate, think, surprised, ok, idea ou time, centralizado em at; ou ./file.json, um arquivo Lottie que a pessoa deu, ao lado da receita. O build coloca dentro do arquivo, com seus créditos — e o arquivo cresce de cerca de 340 KB para cerca de 610 KB (o player e a animação):

lottie celebrate at 720,180 size=120

Números que seguem o valor:

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

Algo que nenhum prop desenha: crie em uma grade 0–100 (números inteiros, y para baixo; fica em 50,100) e então use seu nome:

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"

Esperando pela pessoa, e um quiz (ambos para uma turma):

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

Mantenha: 8 a 40 passos em um quadro; narração curta apenas quando a ideia muda; títulos 36 a 44, rótulos 24 a 34, nada abaixo de 22; cores grafite (o padrão), #2F5BEA, #C8442C, #2E8F62, #8C8578, marcador #FFE45C, no máximo três acentos; fatos e números corretos — nunca invente uma citação ou um número. Outros passos (circle, curve, card, table, axis, timeline, brace, note, move…) estão em references/text.md; o que cada um desenha, em references/recipe.md. Abra-os apenas quando precisar de um passo que não está acima ou a mensagem do build não resolve um erro.

Se a pessoa der um diagrama Mermaid, mantenha-o como está, adicione linhas %% title …, %% # chapter e %% > narration e salve-o como <id>.mmd (references/text.md mostra como). Salve a receita na pasta em que a pessoa trabalha, ou, quando existir uma pasta de saídas para arquivos que a pessoa baixa (no claude.ai, /mnt/user-data/outputs), lá.

3. Construa e verifique

node scripts/build.mjs <id>.chalk

Isso escreve <id>.html ao lado da receita e imprime:

• ✗ text: line N … ou ✗ contract: … (exit 1, nada escrito): corrija essa linha como a mensagem indica, conforme o exemplo abaixo dela.
• ! review … (exit 3): desenhado, mas algo sai do papel, um texto cobre outro ou uma linha cruza um texto. Corrija e construa novamente com --snapshots: ele também escreve <id>.snapshots/<id>.contact-sheet.png — cada capítulo em cada configuração dos valores. Abra essa imagem e corrija o que a revisão nomeou e qualquer coisa que não pareça legível (uma figura que não é reconhecível, um canto lotado, um texto muito pequeno).
• ✓ review, ou • review … the page checks itself when opened (sem navegador aqui): pronto.
• • figures … defined: a receita faz uma figura com define, e a revisão apenas a mede — abra a contact-sheet uma vez e verifique se a figura se lê como a coisa que deveria ser.
• ✗ review not checked: …: pronto, mas diga à pessoa que o desenho não foi verificado.

No máximo duas rodadas de correções; então entregue e diga em palavras simples o que sobrou ("com 15 % o rótulo toca o título").

Várias lições (um curso): uma receita cada, construídas juntas — node scripts/build.mjs one.chalk two.chalk --out course.html --title "O curso". Para um README (ou onde apenas uma imagem for necessária), quando solicitado: node scripts/build.mjs <id>.chalk --svg escreve <id>.svg, uma imagem que se desenha sozinha; a lição ainda é o .html.

4. Entregue

Dê o caminho do .html (ou o próprio arquivo onde a pessoa baixa arquivos) e, em uma linha, o que você escolheu e uma oferta para mudar: "Liguei a uma fatura de cartão de crédito, para alguém que nunca estudou juros, com a taxa mensal para mover — quer outra âncora, outro público ou algo diferente?" Então uma frase sobre o que olhar ("Pressione Próximo; no capítulo 3, mova a taxa"). O arquivo abre offline, com capítulos, os valores ao lado do papel, e download em PNG, SVG, GIF e WebM — pode ser enviado por e-mail ou em um projetor.

Para apresentá-lo (uma palestra, uma turma em um projetor): construa com --present — a página abre um capítulo por vez, tela cheia e as notas do apresentador com a primeira tecla; PageDown de um clique avança. Um PowerPoint, quando solicitado: --pptx (um slide por capítulo; steps aumenta o desenho clique a clique, video incorpora cada capítulo se desenhando), com a narração como notas do apresentador.

Para uma turma

Quando o desenho for para uma turma, alunos, uma palestra ou um curso, pergunte primeiro, em uma mensagem: até três âncoras, a melhor primeiro, cada uma com uma linha sobre por que funciona para aquele público (references/hooks.md), quem exatamente é o público, e qual número os alunos podem mover. Nunca pergunte o que já foi dito. Então mostre o esboço das quatro partes em poucas linhas e aguarde o sinal verde ("pode", "go"). A receita adiciona theme chalkboard, um pause ask abrindo a parte que o responde, e um quiz no final.

Sem execução de código (um artifact)

Onde você não pode executar código mas pode mostrar um artifact HTML, coloque a receita nesta pequena página — nada mais — e mostre-a. O player carrega do CDN e verifica a receita ele mesmo:

<!doctype html>
<meta charset="utf-8">
<title>TÍTULO DA LIÇÃO</title>
<script type="text/chalk-talk" id="chalk-recipe">
A RECEITA COMO TEXTO
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>

Se a página disser que a receita não pôde ser aberta, corrija a linha que ela nomeia.

Alterando depois

"Deixe a seta azul", "adicione uma segunda pessoa", "use 5 % em vez disso": mude apenas o que foi solicitado, mantenha o resto, construa novamente e diga o que mudou. Uma âncora ou público diferente é um novo desenho.

Nunca

• Nunca edite assets/ ou scripts/contract.mjs: eles são gerados.
• Nunca coloque HTML, links, scripts ou imagens em uma receita: textos são texto simples, cores são hex ou nomes.
• Nunca escreva um script para gerar a receita: escreva você mesmo (expressões e repeat fazem a aritmética).
• Sem execução de código, nunca escreva o player, um SVG ou uma imagem do desenho à mão: use a pequena página acima. Se você não pode nem executar código nem mostrar um artifact, diga isso e dê a receita.