Passo 13 · As ferramentas · As ferramentas · Loop Engineering ENPT
Passo 13 · As ferramentas

visual-teach: o motor que construiu este curso

Aqui está a lição mais meta do curso inteiro: esta própria página foi feita pelo visual-teach. Cada lição que você leu — o visual neutro-quente, o toggle de modo escuro, os demos ao vivo, a camada Simples-depois-Técnico, as versões em inglês e em português do Brasil — saiu de um motor que transforma um tópico num curso HTML interativo e autocontido. E o motor não rodou sozinho: o loop que você vem aprendendo trata um curso visual-teach finalizado como um entregável — o seu Course Gate — para que a mesma disciplina LEARN → ANALYZE → EXECUTE → VERIFY que entrega código também entregue o ensino sobre ele. Esta lição abre o motor e deixa você operar suas partes.

Leia a camada simples de cima a baixo; abra um painel quando quiser o arquivo, o token ou o passo de build exato. Aperte cada demo — eles estão ao vivo.
1

A grande ideia: um tópico entra, um curso interativo inteiro sai


A maioria das ferramentas que "explicam" algo te entrega um paredão de texto. O visual-teach faz algo diferente: você dá um tópico a ele, e ele produz um pequeno site que ensina aquele tópico — um conjunto de páginas HTML que abrem com um duplo-clique, não precisam de internet e deixam o leitor cutucar as ideias em vez de só ler sobre elas.

Cada página é feita pela mesma receita. Há uma camada em linguagem simples e amigável que qualquer pessoa consegue acompanhar, e uma camada técnica dobrada atrás de um toggle para o leitor que quer o detalhe exato. Há diagramas desenhados como vetores, para que fiquem nítidos e se recolorizem sozinhos no modo escuro. Há demos ao vivo — pequenos simuladores, animações, sliders, slide decks — que transformam uma frase em algo que você opera. E o conjunto todo é entregue em dois idiomas por padrão: inglês e português do Brasil.

O truque que mantém tudo junto é um único shell compartilhado. A barra do topo, a navegação lateral, as cores, as fontes, o botão de modo escuro — tudo isso é byte a byte idêntico em toda página. Só o meio, a lição em si, muda. Assim um curso de 14 lições parece um produto único e consistente, não 14 páginas feitas à mão que vão se distanciando.

Pense nisso como uma revista impressa com um estilo editorial rígido. Todo artigo fica na mesma grade, mesmo cabeçalho, mesmas fontes, mesma mobília de página — então o leitor nunca precisa reaprender a ler. Os autores só preenchem o poço do artigo; o template garante o resto. O visual-teach é esse estilo editorial, só que os "artigos" são interativos e o template é imposto em código. Onde a analogia quebra: o template de uma revista é uma sugestão que um designer pode sobrescrever discretamente; aqui o shell é copiado ao pé da letra e qualquer divergência entre duas páginas é tratada como defeito.

O que "autocontido" te dá

Toda página é um único arquivo .html com CSS inline, SVG inline e JS puro inline — zero requisições externas. Sem CDN, sem web font, sem <img>, sem raster data:. É isso que torna um curso abrível a partir de file://, enviável como anexo de e-mail, arquivável e seguro de ler num avião. O custo é disciplina: nada de framework, nada de passo de build, e cada diagrama desenhado como vetor à mão.

O layout padrão

Um curso é um hub (index.html), uma pasta de lições (lessons/0001…), uma página de galeria opcional e os exemplares de demo brutos. O inglês vive na raiz; cada tradução espelha a árvore inteira sob seu código (pt/index.html, pt/lessons/…) com os mesmos nomes de arquivo. O seletor .vc-lang lista exatamente os idiomas que existem, e nunca aponta para um link morto.

O documento de referência, não só a lição

O visual-teach destila duas coisas ao mesmo tempo: a lição narrativa (lida uma vez) e um documento de referência durável (retornado vez após vez — folhas de cola, glossários, fluxogramas). O arquivo de pedagogia chama o documento de referência de "a metade durável" — a parte que a maioria do ensino esquece. As páginas por lição deste curso funcionam também como essa referência.

2

Por que o loop construiu um curso afinal


Você passou doze lições num loop que entrega trabalho: ele aprende o estado real, analisa a lacuna, executa uma unidade delimitada e verifica o resultado num boundary real antes de decidir o que fazer em seguida. O visual-teach é onde esse loop paga um segundo dividendo. Quando um trabalho fica pronto, o loop não te entrega só o artefato — ele também pode te entregar o ensino sobre ele, gerado como um curso visual-teach completo. Esse entregável é o Course Gate do loop.

Então este curso não é um projeto paralelo aparafusado no loop. Ele é uma saída do loop. O mesmo motor que provou que o código funciona também produziu a lição que explica como ele funciona — e é exatamente por isso que "o motor que construiu este curso" é mais do que um slogan.

Pense num laboratório de pesquisa. O experimento é o trabalho; o artigo publicado é como o conhecimento sobrevive além das pessoas que o conduziram. Um laboratório que nunca registra seus resultados os perde. O Course Gate é o passo de registro tornado automático — o loop termina o experimento e arquiva o artigo na mesma execução. Onde quebra: um artigo é prosa somente-leitura; um curso visual-teach é interativo e re-testável, mais perto de um artigo que você pode rodar.

LEARN ANALYZE EXECUTE VERIFY DECIDE próxima? convergiu Course Gate rode visual-teach curso hub + lições EN + PT-BR autocontido
O loop roda até convergir, então o Course Gate roda o visual-teach para emitir o ensino — este próprio curso.

Gate, não algo de última hora

No vocabulário do loop um gate é uma verificação que você não pode pular. O Proof Gate prova que o artefato funciona num boundary real; o Course Gate prova que o conhecimento foi capturado e é ensinável. Ambos são entregáveis da mesma execução, então "a gente entregou mas nunca documentou" deixa de ser possível por construção.

Tudo continua rodando AFK

Gerar o curso não é uma tarefa braçal humana. Sob o loop, um executor constrói cada lição e um validador independente a confere contra a meta — o único papel do humano é a observabilidade (ler o log, a revisão, o status). O Course Gate herda exatamente isso: um curso é produzido e verificado sem uma pessoa escrevendo HTML à mão.

3

Em uma imagem: a anatomia de um curso


Antes das partes, o todo. Um curso visual-teach são quatro tipos de coisa conectados. Leia a folha de cima a baixo; cada caixa diz o que é e onde mora no disco.

Hub index.html Lições lessons/0001 … 0014 Galeria gallery.html · opcional Exemplares de demo 20 tipos copiáveis Espelho PT-BR pt/index · pt/lessons/… liga liga extraído para espelha EN→PT
Um hub, muitas lições, uma galeria opcional, uma paleta de exemplares de demo — e a árvore inglesa inteira espelhada em pt/.

Onde cada peça mora

O hub (index.html) é construído a partir de assets/index-template.html e é a única página que agrupa lições por Módulo. As lições são construídas a partir de assets/lesson-template.html. Os exemplares de demo sob assets/demos/NN-slug.html não são entregues ao leitor — são a fonte de onde você extrai markup, CSS e JS ao preencher uma lição. A galeria é um índice opcional dos demos ao vivo.

O espelho é estrutural

PT-BR não é um toggle de tradução dentro de um arquivo; é uma árvore de diretórios paralela. pt/lessons/0013-visual-teach.html é o mesmo arquivo que o inglês com <html lang="pt-BR">, o .cur trocado em .vc-lang, a profundidade dos links relativos corrigida, e só a prosa traduzida — nunca o código, os comandos ou os identificadores.

4

O shell byte-idêntico: um padrão, toda página


A regra mais importante do motor também é a mais simples: as partes da página que não são a lição são copiadas exatamente iguais em toda página. Os tokens de cor, os estilos base, a step-bar do topo com seu botão de modo escuro e seletor de idioma, a navegação lateral, a wizard nav de baixo, o rodapé e o JavaScript compartilhado — tudo isso é um bloco de bytes, repetido ao pé da letra.

Só dois espaços são próprios de uma lição: um lugar para o CSS extra da lição (a estilização dos seus demos) e um lugar para o JavaScript da lição (a fiação desses demos). Todo o resto é proibido. Se você precisasse de um novo componente compartilhado, você o adicionaria ao template para que todas as páginas o recebessem — você nunca o estilizaria numa página só.

Pense numa rede de cafés. Entre em qualquer filial e o balcão, o cardápio na parede, os tamanhos de copo e a sinalização são idênticos — só as ofertas do dia mudam. Você pede sem pensar porque o layout nunca se mexe. O shell é essa montagem fixa; a lição é a oferta do dia. Onde quebra: um gerente de café pode repintar uma parede; aqui a montagem é imposta byte a byte, e duas filiais que diferissem seriam um bug.

:root design tokens (claro + escuro) — COMPARTILHADO, idêntico CSS base + stepbar + toggle de tema + seletor de idioma — COMPARTILHADO nav lateral (.vc-aside) + índice do curso — COMPARTILHADO ▸ CSS DA LIÇÃO — o único espaço de estilo que você preenche ▸ CONTEÚDO DA LIÇÃO (o marcador) + JS DA LIÇÃO prosa · SVGs · demos — isto é tudo que muda wiznav (anterior · índice · próximo) + rodapé — COMPARTILHADO JS compartilhado: persistência de tema + toggles Simples/Técnico — COMPARTILHADO
As faixas cinzas são byte a byte idênticas em todas as páginas. As duas faixas em clay são os únicos espaços que uma lição preenche.

assets/lesson-template.html — os dois espaços, ao pé da letra

/* ===== BEGIN SHARED SHELL (byte-identical across all pages) ===== */
/* … tokens, base CSS, stepbar, nav … copy verbatim, never edit per page … */
/* ===== END SHARED SHELL ===== */

/* ===== LESSON-SPECIFIC (only this lesson's demo CSS goes here) ===== */
.d05_btn { background: var(--btn-bg); /* uses shared tokens → dark mode for free */ }
/* ===== END LESSON-SPECIFIC ===== */

Por que byte a byte idêntico, não "basicamente igual"

Se cada página escreve seu próprio cabeçalho à mão, as páginas divergem: um padding aqui, uma cor ali, um link de nav desatualizado em outro lugar. Ao exigir o shell como um bloco copiado, um curso de qualquer tamanho tem exatamente um cabeçalho, um rodapé, uma nav, um conjunto de tokens e um motor de tema. Auditar é trivial — faça o diff de duas páginas quaisquer e só o corpo da lição e seu CSS/JS devem diferir.

Como o modo escuro pega carona de graça

O shell entrega dois blocos :root: a paleta clara e um override :root[data-theme="dark"] que redefine os mesmos nomes de variável. Como todo componente (e os demos desta lição) lê var(--token) e nunca um hex chumbado, virar um atributo no <html> re-tematiza a página inteira. Um script de pré-pintura no <head> aplica o tema salvo ou o preferido do SO antes da primeira pintura, então não há flash claro.

O JS próprio da lição tem namespace

Cada demo extraído prefixa todo id, classe, marker de SVG e busca no DOM com uma tag única (esta lição usa d05_, d07_, d08_, d09_, d10_, d15_, d19_). É isso que permite cinco ou sete demos independentes coexistirem numa página sem uma única colisão.

5

O pipeline de build, em 6 slides


Como um tópico de fato vira um curso finalizado? Clique por este deck para ver o formato disso em dois minutos — uma ideia por slide. Depois, os dois próximos demos deixam você assistir o pipeline rodar e conduzir uma única lição por ele.

A entrada

Começa com um tópico e um currículo.

Mapeie o assunto em Módulos e lições, decida o exemplo condutor e escolha quais tipos de demo vão ensinar cada momento. O plano é o contrato de tudo que vem depois.

Scaffold

Carimbe toda página a partir de um template.

Cada lição começa como uma cópia do shell compartilhado com um marcador FILL onde o corpo entra. A stepbar, a nav, os tokens e o rodapé já estão corretos e idênticos — ninguém constrói a mobília de página à mão.

Fill

Despeje prosa, SVGs e demos ao vivo.

Substitua o marcador pela lição: uma camada Simples, uma camada Técnica, diagramas desenhados à mão e demos extraídos dos exemplares — cada id com namespace para que nada colida.

Mirror

Clone a árvore para o português do Brasil.

Copie cada página inglesa para pt/, defina lang="pt-BR", vire o seletor de idioma, corrija a profundidade dos links e traduza só a prosa — código, comandos e identificadores permanecem em inglês.

Verify

Prove no boundary real.

Abra a partir de file:// com zero requisições, faça o diff do shell em busca de divergência, alterne o modo escuro, cheque se cada link de idioma resolve, confirme que cada demo está ao vivo. Uma alegação não é prova — a página é aberta e exercitada.

Conclusão

Scaffold, fill, mirror, verify — então entregue.

O pipeline é um loop em miniatura: unidades delimitadas, cada uma verificada no boundary, EN e PT-BR entregues juntas. Acerte esses quatro momentos e o curso fica consistente, durável e autocontido.

1 / 6 Use as setas

Por que um deck para a visão geral

Um slide deck é o tipo de demo certo quando o trabalho é "captar o formato de um tópico inteiro antes do detalhe". Cada slide carrega exatamente uma ideia em tipografia grande, então o leitor nunca equilibra dois pensamentos de uma vez. O motor é uma função go(index) limitada a [0, n-1] que alterna o slide atual, preenche a barra de progresso, sincroniza a trilha de pontos e desabilita Anterior/Próximo nas pontas — setas do teclado incluídas, com o movimento respeitando prefers-reduced-motion.

Scaffold → fill → mirror → verify, com precisão

Scaffold copia o template (shell intacto, corpo um marcador). Fill substitui o marcador, adiciona o CSS do demo ao único espaço de CSS e a fiação ao único espaço de JS. Mirror produz o gêmeo pt/. Verify é o Proof Gate para o ensino: abra o arquivo, faça o diff do shell, exercite os demos, resolva cada link — nunca afirme "deveria funcionar".

6

Veja o pipeline rodar, um momento de cada vez


Um deck te diz os passos; uma animação mostra a ordem. Aperte Play para mandar uma lição pelo pipeline, Step para avançar um momento, ou Reset para recomeçar. Observe o token viajar: do scaffold ao fill, depois um espelho se abre para o gêmeo PT, e então o verify o prova antes de entregar.

pronto
template + marcador FILL scaffold fill página EN página PT-BR verify Proof Gate PT
Leia da esquerda para a direita: template → scaffold → fill → (espelha para PT) → verify → ship. Aperte Reproduzir.

Pronto. Aperte Reproduzir ou Avançar para mandar uma lição pelo pipeline.

Uma máquina de estados minúscula, não um vídeo

Cinco fases ordenadas — scaffold, fill, mirror, verify, ship — movem um motor em JS puro. Cada passo interpola a posição do token com requestAnimationFrame e uma curva ease-in-out; o momento do espelho gera um segundo token que se abre para baixo até o gêmeo PT. Não há <video>, nem GIF, nem biblioteca, então ele avança, reproduz e reinicia de forma determinística e respeita prefers-reduced-motion saltando em vez de interpolar.

Por que animar em vez de desenhar

Um diagrama estático responde "o que está conectado". Esta animação responde "em que ordem, e onde o gêmeo PT se ramifica". Recorra à animação só quando a sequência é a lição — caso contrário um estático com rótulos custa menos e lê mais rápido.

7

Conduza o ciclo de vida de uma lição você mesmo


Agora você conduz. Uma lição percorre um conjunto fixo de estados, e o ponto todo é que você não pode pular: você não pode entregar uma lição que nunca foi verificada, e uma página que falha na verificação volta para ser corrigida, não para frente. Aperte um evento e observe o estado destacado se mover; os botões ficam cinza no instante em que um movimento não é permitido de onde você está.

fill mirror verify fail refill ship Montada SCAFFOLD Preenchida FILLED Espelhada MIRRORED Verificada VERIFIED Precisa ajuste NEEDSFIX Entregue · final

O nó preenchido em clay é onde esta lição está agora. Nós esmaecidos são inalcançáveis daqui.

Estado atual

SCAFFOLD

Uma cópia do template com o shell intacto e um marcador FILL onde o corpo entra. Nada ensinado ainda.

Transições permitidas

Log de eventos

    O ciclo de vida inteiro em um objeto

    Tudo que o protótipo faz é movido por esta tabela. Os botões a leem para decidir o que habilitar; apertar um consulta machine[state][event] e move para lá. Os movimentos ilegais — entregar antes de verificar, espelhar antes de preencher — simplesmente não existem na tabela, então não podem ser feitos. VERIFIED só pode ship; um verify que falha roteia para NEEDSFIX, cujo único caminho à frente é voltar para FILLED para ser repreenchida e reverificada. Esse é o Proof Gate expresso como uma máquina de estados.

    const machine = {
      SCAFFOLD: { fill:   'FILLED' },
      FILLED:   { mirror: 'MIRRORED' },
      MIRRORED: { verify: 'VERIFIED', fail: 'NEEDSFIX' },
      NEEDSFIX: { refill: 'FILLED' },
      VERIFIED: { ship:   'SHIPPED' },
      SHIPPED:  {}            // terminal — the course gate is satisfied
    };
    8

    A paleta de 20 demos, agrupada por família


    O que torna uma lição viva em vez de uma página de texto é o demo. O visual-teach entrega 20 tipos de demo prontos — pequenos widgets autocontidos que você copia e refia. São uma paleta, não uma checklist: uma ideia simples pode usar um; uma lição rica (como esta) empilha sete. Eles se dividem em um punhado de famílias pelo trabalho de ensino que cada um faz.

    Explicar como funciona 04 code-understanding · 10 svg-illustrations · 14 feature-explainer · 15 concept-explainer Comparar opções / variantes 01 code-approaches · 02 visual-designs · 05 design-system · 06 component-variants Um processo no tempo / ramificação 07 prototype-animation · 08 prototype-interaction · 13 flowchart-diagram Ler estado · ensinar pela falha 11 status-report · 12 incident-report Resumir · narrar / planejar uma mudança 09 slide-deck · 03 code-review · 16 implementation-plan · 17 pr-writeup · 18 triage-board Ajustar controles / toggles 19 editor-feature-flags · 20 editor-prompt-tuner
    Vinte tipos, seis famílias. Escolha pelo trabalho de ensino do momento — e varie-os ao longo de um curso para que o leitor continue engajado.

    E aqui está a própria família "ajustar toggles", tornada ao vivo — o tipo de demo 19. Estes são justamente os interruptores que decidem com o que um curso é entregue. Vire-os e observe os avisos: algumas escolhas dependem de outras.

    Modo escuroOverride de tokens + um toggle na stepbar. Padrão em toda página.
    Inglês (raiz)A árvore base na raiz do curso. Obrigatória — o curso não pode ser entregue sem idioma algum.
    Espelho em português do BrasilA árvore pt/. Entregue por padrão — desligá-la deixa o link de idioma PT morto.
    Demos interativos ao vivoOs widgets extraídos. Sem eles uma lição é prosa — conhecimento, mas sem prática de habilidade.
    Autocontido (zero requisições)Tudo inline. Desligá-lo permitiria um CDN — e quebraria file:// + offline.

    Status do build

      Escolha pelo trabalho, depois varie

      Para cada momento de uma lição você nomeia o trabalho de ensino em uma frase — explicar como funciona, comparar opções, mostrar um processo no tempo, ler estado, ensinar pela falha, resumir, deixar conduzir, ajustar controles — liste dois ou três tipos candidatos, escolha o que melhor encaixa com uma razão de uma linha e nomeie o vice que você rejeitou. Um curso completo exercita a maioria ou todos os vinte; reusar um widget a cada momento é um cheiro ruim.

      Feature flags com dependências

      Os interruptores acima são o tipo de demo 19. Cada toggle lê uma pequena tabela de regras: desligar autocontido permite um CDN mas quebra o uso offline; desligar o espelho PT deixa o link de idioma órfão; desligar os demos rebaixa a camada de habilidades para somente-conhecimento. O painel revela essas consequências ao vivo — exatamente o que este tipo de demo ensina: um toggle nunca é livre de efeitos colaterais.

      9

      A paleta de ilustrações SVG: diagramas que sobrevivem ao modo escuro


      Todo diagrama que você viu neste curso é desenhado à mão como um SVG inline — formas vetoriais escritas na página, nunca um arquivo de imagem. É por isso que eles ficam nítidos como navalha em qualquer tamanho e por que se recolorizam quando você vira para o modo escuro. Há uma paleta rígida para que leiam tanto no marfim claro quanto no fundo quase-preto. Toque numa amostra abaixo para destacar uma regra dessa paleta no exemplo trabalhado.

      Pense num diagrama de vista explodida num manual de móveis: cada painel e parafuso desenhado no lugar com uma linha até o nome dele. Você não o lê — você onde cada peça vai. Uma folha SVG é isso, mas também obedece a uma disciplina de cor para que nunca desapareça numa página escura.

      uma folha SVG segura no escuro · lê no claro E no escuro fill="none" banho rgba(…, .14) para ênfase clay · olive · sky · rust · gray um <marker> compartilhado branco só SOBRE um chip de cor Caixas não têm preenchimento mostram a superfície tematizada atrás Ênfase é um banho semitransparente, funciona sobre qualquer bg Traços do meio da paleta cinco hexes que leem nos dois temas Um marker de seta definido uma vez, reusado por cada linha Branco é a exceção só um glifo sobre um chip de cor
      A paleta segura no escuro inteira numa folha. Toque numa amostra abaixo para destacar uma regra.

      Nenhuma amostra selecionada não esmaece nada — escolha uma para destacá-la, ou "Mostrar tudo" para reiniciar.

      Por que hex, não var(), no SVG

      As custom properties do CSS não resolvem de forma confiável dentro de atributos de apresentação do SVG (fill="…", stroke="…") entre renderizadores, então os diagramas usam os hexes literais do meio da paleta — clay #D97757, olive #788C5D, sky #5C7CA3, rust #B04A3F, gray #87867F. Cada um lê tanto na superfície marfim quanto na quase-preta. As caixas são fill="none" para que a superfície tematizada da página apareça atrás; o único preenchimento branco permitido é um glifo sobre um chip de cor saturada.

      Acessibilidade e movimento

      Todo <svg> carrega role="img" e um aria-label que lê o diagrama inteiro como uma frase, então um usuário de leitor de tela recebe o mesmo conteúdo. Um único <marker> de seta é definido uma vez por SVG e reusado. Onde um diagrama anima, ele honra prefers-reduced-motion.

      10

      O design system compartilhado: os tokens por trás de toda página


      O visual neutro-quente em que você vem lendo não é improvisado por página — é um pequeno design system: um conjunto fixo de cores e tamanhos nomeados (os tokens) dos quais toda página bebe. Ninguém escreve um hex cru como #D97757 na lição; escreve o nome --clay. Mude o valor do nome uma vez e todo botão, título e borda se atualizam juntos — e esse é exatamente o mecanismo que torna o modo escuro uma virada de uma linha.

      Pense numa cozinha com potes rotulados. Ninguém pega de um saco sem rótulo torcendo para que seja açúcar — vai ao pote que diz "Açúcar". Tokens são os rótulos; a regra é sempre vá ao pote, nunca ao saco cru. Onde quebra: o conteúdo de um pote é fixo, mas o valor de um token é trocado por inteiro pelo tema — o mesmo rótulo, um açúcar diferente no escuro.

      Tokens de cor (a paleta real deste curso)

      --ivory#FAF9F5 · fundo de página
      --slate#141413 · tinta
      --clay#D97757 · primário
      --clay-d#B85C3E · hover do primário
      --olive#788C5D · sucesso
      --sky#5C7CA3 · informação
      --rust#B04A3F · perigo
      --oat#E3DACC · preenchimento sutil
      --gray-100#F0EEE6 · fundo suave
      --gray-500#87867F · texto tênue

      Tokens de tipografia & raio

      --seriftítulos (Georgia)
      --sanscorpo · 17px/1.75
      --monocódigo · rótulos · nav
      --radius-panel14px · cards
      --radius-row9px · linhas/chips
      espaço de seção52px · ritmo

      Agora torne concreto. Escolha um intuito e um tamanho — o botão de preview é estilizado a partir de tokens, e o readout de código mostra os tokens exatos em jogo. É exatamente assim que um componente orientado a tokens se comporta: troque os valores, o componente re-renderiza, sem CSS novo.

      Intuito

      Tamanho

      tokens resolvidos
      .btn { }

      Tokens primitivos vs semânticos

      Duas camadas importam. Tokens primitivos são valores crus (--clay: #D97757). Tokens semânticos os apelidam por papel (--btn-bg: var(--clay)). Os componentes consomem só os semânticos, então re-tematizar significa reapontar um alias, nunca tocar no componente. O botão de preview não carrega classe por intuito — cada controle escreve as custom properties semânticas no seu style inline, e uma regra .d05_dsbtn as lê com var().

      assets/lesson-template.html — :root (trecho)
      /* primitive scale */
      --clay:   #D97757;
      --clay-d: #B85C3E;
      --olive:  #788C5D;
      --rust:   #B04A3F;
      
      /* dark mode redefines the SAME names → every var() flips */
      :root[data-theme="dark"] { --clay: #E08A6B; --ivory: #1A1917; /* … */ }
      11

      Dois leitores, uma página: Simples ↔ Técnico


      Uma única lição precisa servir a dois leitores muito diferentes: alguém encontrando a ideia pela primeira vez, e alguém que quer o comando exato e o caso de borda. O visual-teach não escolhe um — ele empilha os dois. A camada Simples está sempre visível e deve contar a história inteira por conta própria. A camada Técnica fica dobrada atrás de um toggle, então o detalhe preciso está a um clique para o leitor que opta por ele — e invisível para quem não opta. Todo botão "Mostrar o detalhe técnico" nesta página é esse mecanismo. (Há também um controle "Expandir tudo" no topo que os abre juntos.)

      Pense nas etiquetas de museu. O grande texto de parede dá a todos a história em uma frase; o cartãozinho ao lado da peça adiciona a data, a técnica e a procedência para quem quiser. Ninguém é forçado a ler o cartãozinho, e ninguém que o queira é privado dele. Onde quebra: um museu imprime os dois estaticamente; aqui o cartãozinho é recolhível, então o leitor casual nem se distrai com ele.

      Camada Simples sempre visível palavras simples · uma analogia · concreto antes do abstrato deve se sustentar sozinha → história inteira, sem precisar de toggle opcional Camada Técnica atrás de um toggle comando exato · números reais · casos de borda · o caminho do arquivo complementa, nunca repete o jargão é correto aqui
      A camada Simples é completa por conta própria; a camada Técnica adiciona precisão para o leitor que a abre.

      O teste de autonomia

      A regra que o motor impõe: oculte todo painel técnico e a camada Simples ainda precisa fazer sentido e alcançar a única vitória da lição. Se não alcança, a camada Simples está incompleta. Introduza o termo depois da ideia — "a coisa que decide para onde sua requisição vai … isso se chama load balancer" — para que o jargão seja conquistado, não presumido. Frases curtas, uma ideia cada, segunda pessoa, presente.

      O mecanismo

      Cada toggle é um <button class="tech-toggle" aria-expanded> cujo irmão seguinte é um painel .technical; clicar vira aria-expanded e alterna .open. O #expandAll no nível da página abre ou fecha todos de uma vez e fica em sincronia. Essa fiação vive no JS compartilhado, então toda lição a ganha de graça — esta lição não escreveu uma linha dela.

      12

      O que todo curso entrega por padrão


      Juntando os fios, eis o contrato que todo curso visual-teach cumpre sem ninguém pedir. Ele abre com um duplo-clique sem internet. Ele carrega o shell byte a byte idêntico em toda página. O modo escuro funciona e lembra sua escolha. Ele entrega inglês e português do Brasil juntos — nunca inglês com links PT mortos. Todo diagrama é vetor seguro no escuro. Toda lição começa pela camada Simples e mostra código ou comandos reais com um jeito de chegar até eles. E não há nenhuma atribuição a IA em lugar algum — o artefato se sustenta sozinho.

      Pense no kit de segurança padrão de um carro. Você não marca uma caixinha para cintos, airbags e espelhos — eles vêm de fábrica por lei em todo modelo. Esses padrões são o kit padrão do visual-teach: não extras opcionais que você lembra de adicionar, mas a base sem a qual um curso não pode ser entregue.

      autocontido · zero requisições shell compartilhado byte a byte idêntico modo escuro, persistido EN + PT-BR, ambos construídos diagramas vetoriais seguros no escuro Simples → Técnico + código real nenhuma atribuição a IA — em lugar algum um exemplo condutor, costurado citado de fontes reais
      O kit padrão. A marca em rust é o único item formulado como proibição rígida: nunca atribua o artefato a uma IA.
      13

      A pedagogia por baixo: por que ensina do jeito que ensina


      Nenhuma dessas escolhas é decoração. O visual-teach é construído sobre uma teoria específica de como as pessoas de fato aprendem, e três ideias movem quase toda decisão na página.

      Primeiro, aprender precisa de três coisas diferentes: conhecimento (fatos, tirados de fontes confiáveis, nunca inventados), habilidades (construídas só fazendo — é por isso que os demos existem) e sabedoria (julgamento, conquistado pela prática real numa comunidade). Uma lição pondera essas coisas de modo diferente dependendo do tópico.

      Segundo, há uma diferença entre fluência e força de armazenamento. Reler algo faz parecer familiar — isso é fluência, e ela esvanece rápido. A memória durável — a força de armazenamento — é construída por recuperação (lembrar a partir de uma página em branco), espaçamento (revisitar ao longo do tempo) e intercalação (misturar ideias relacionadas). Essa é toda a razão de este curso ensinar cada ideia central de várias formas — uma analogia, um diagrama, um demo ao vivo, um exemplo trabalhado e uma verificação — e retestá-la.

      Terceiro, a zona de desenvolvimento proximal: encontre o leitor logo além do que ele já sabe — nem tão fácil que entedie, nem tão difícil que sobrecarregue. Para conhecimento puro, a dificuldade é a inimiga (ela devora a memória de trabalho que você precisa para entender); para habilidades, um pouco de dificuldade é a ferramenta que fixa.

      Pense em aprender a dirigir. Ler o manual é conhecimento; parece progresso, mas você não dirige a partir dele. A habilidade vem só do tempo ao volante com feedback instantâneo — saiu da faixa, o instrutor fala agora, não semana que vem. E um bom instrutor te mantém logo além do confortável: a lição de hoje é um pouco mais difícil que a de ontem, nunca uma rodovia no primeiro dia.

      tempo → retenção fluência — parece aprendizado, esvanece armazenamento — mais lento, durável recuperar espaçar intercalar Zona de desenvolvimento proximal fácil demais — tédio logo além do que você sabe difícil demais — sobrecarga
      Reler compra fluência que esvanece; recuperação, espaçamento e intercalação constroem força de armazenamento que dura — ensinada na zona logo além do que você sabe.

      Então aqui está a própria prática de recuperação — a verificação rápida do tipo de demo 15. Lembre primeiro, depois revele. Escolha a resposta em que você acredita antes de clicar; o feedback é imediato. (Toda opção tem o mesmo comprimento, então a formatação não entrega nada.)

      Q1 Por que o curso ensina uma ideia de várias formas diferentes?

      Q2 O que a camada Simples precisa fazer inteiramente por si só?

      Q3 Para conhecimento puro (não habilidade), a dificuldade ao aprender é…

      Escolha uma resposta em cada questão.

      Mini-glossário

      Força de armazenamento
      Retenção durável de longo prazo — a meta real. Construída por recuperação, espaçamento e intercalação.
      Força de fluência
      Facilidade do momento que parece domínio mas decai rápido. Reler a infla.
      Zona de desenvolvimento proximal
      A faixa logo além do que um aprendiz já consegue fazer sozinho — onde o ensino mais rende.
      Documento de referência
      O destilado durável e reutilizável — folha de cola, glossário, fluxograma — ao qual se retorna muito depois da lição.

      Desenhar a verificação para que a formatação não entregue nada

      Toda opção num quiz tem a mesma contagem de palavras — idealmente a mesma contagem de caracteres — para que a opção mais longa e mais qualificada nunca entregue a resposta. Os distratores são plausíveis e batem com um equívoco real, o que ensina mais do que uma opção obviamente errada. O feedback é imediato (o loop apertado que as habilidades precisam), e "Tentar de novo" deixa o leitor espaçar a recuperação.

      Conhecimento fácil, habilidades custosas

      A divisão importa: na camada de conhecimento, a dificuldade é removida (prosa clara, uma ideia por frase) porque a memória de trabalho é minúscula e você quer gastá-la entendendo. Na camada de habilidades — os demos e o quiz — um pouco de dificuldade desejável (lembrar antes de revelar, conduzir a máquina você mesmo) é exatamente o que converte fluência em força de armazenamento.

      14

      No código: o template, os demos, o build


      Tudo nesta lição veio de um punhado de arquivos reais. Aqui está onde eles moram e como abri-los, para que o motor não seja uma caixa-preta.

      ~/.claude/skills/visual-teach/ — o motor

      # the one shell every page copies, byte-for-byte
      assets/lesson-template.html      # BEGIN/END SHARED SHELL + two fill slots
      assets/index-template.html       # the hub, grouped by Module
      
      # the 20 copyable demo exemplars (lift markup + CSS + JS)
      assets/demos/05-design-system.html
      assets/demos/07-prototype-animation.html
      assets/demos/08-prototype-interaction.html
      assets/demos/09-slide-deck.html
      assets/demos/10-svg-illustrations.html
      assets/demos/19-editor-feature-flags.html
      assets/demos/15-research-concept-explainer.html
      
      # the four reference files that govern the build
      references/build-guide.md        # shell, tokens, nav, i18n, the verify checklist
      references/demo-catalog.md        # the 20 types + the debate procedure
      references/svg-patterns.md        # dark-safe inline-SVG rules
      references/teaching-language.md   # Simple-layer + analogy + quiz design
      references/pedagogy.md            # knowledge/skills/wisdom · fluency vs storage · ZPD

      Liste o motor e seus demos

      # every reference and demo exemplar
      ls ~/.claude/skills/visual-teach/references/
      ls ~/.claude/skills/visual-teach/assets/demos/
      
      # the two fill slots in the shared shell
      grep -n "LESSON-SPECIFIC" ~/.claude/skills/visual-teach/assets/lesson-template.html

      Abra este próprio curso

      # the hub and a lesson — open from file://, no server needed
      open ~/courses/loop-engineering/index.html
      open ~/courses/loop-engineering/lessons/0013-visual-teach.html
      
      # confirm zero external requests (no http/https/cdn references)
      grep -nE "https?://(?!.*w3\.org)" ~/courses/loop-engineering/lessons/0013-visual-teach.html || echo "self-contained ✓"

      Como uma lição é preenchida

      Faça o scaffold a partir de lesson-template.html (shell intacto, corpo um marcador <!-- FILL -->), substitua o marcador pelo conteúdo, jogue o CSS de cada demo extraído no único espaço de CSS LESSON-SPECIFIC e a fiação dele no único espaço de JS LESSON-SPECIFIC, dê namespace a todo id/classe/marker por demo, depois espelhe em pt/ e verifique abrindo os dois. Esse é precisamente o pipeline que você assistiu e conduziu acima.

      Você não terminou de aprender aqui — eu sou seu professor nisto. Peça que eu faça o scaffold de uma lição novinha a partir do template, que extraia e refie qualquer um dos 20 tipos de demo num tópico que te interessa, que espelhe uma página para PT-BR, ou que rode a checklist de verificação contra um curso que você construiu. A seguir — o final: um pedido, de ponta a ponta, onde o Forge, o loop e esta caixa de ferramentas inteira rodam juntos num único pedido real.