primary
A única ação principal da tela. Preenchida e chamativa para que o olho pouse nela primeiro.
Evite: duas primárias brigando numa mesma visão.
Você está lendo a saída dele agora mesmo. Quando um loop termina um trabalho, ele não te entrega uma parede de anotações — ele constrói um curso como este: um único arquivo HTML autossuficiente, acolhedor e legível, com modo escuro, diagramas desenhados à mão e pequenas coisas em que você pode clicar. Esta lição abre o motor que o faz, na própria página que esse motor produziu.
Tudo neste suite termina do mesmo jeito. Quando um loop conclui um trabalho — um bug corrigido, uma ferramenta construída, um tema pesquisado — ele não diz apenas "pronto" e despeja uma pilha de anotações cruas em cima de você. Ele pega o que aprendeu e ensina de volta, como um pequeno curso que você consegue de fato ler e navegar clicando. A coisa que transforma um resultado nesse curso se chama visual-teach. A página em que você está agora mesmo é uma das lições dele.
Então esta lição é um pouco incomum: ela explica a própria ferramenta que a produziu. Olhe ao redor enquanto lê. A cor de papel acolhedora, o botão de lua no canto que vira para o escuro, os diagramas desenhados à mão, os painéis "Mostrar o detalhe técnico" que abrem e fecham, o seletor de idioma no topo que diz EN e PT — cada um deles é algo que o visual-teach coloca em cada lição de propósito. Ao final você vai conseguir apontar para qualquer parte desta página e dizer o que o motor estava fazendo quando a criou.
Por que se dar ao trabalho de transformar o trabalho em um curso, afinal? Porque um resultado que você não consegue entender não está realmente finalizado. Uma parede de logs prova que a máquina fez alguma coisa; ela não ajuda uma pessoa a sacar o assunto. O visual-teach existe para que o humano no fim da execução saia de fato entendendo o que aconteceu — do mesmo jeito que um bom professor não devolve só uma prova corrigida, ele a explica.
Uma promessa está por baixo de tudo isso, e vale dizê-la com clareza: um curso visual-teach é um único arquivo que funciona por conta própria. Sem internet, sem instalação, sem servidor. Você pode mandá-lo por e-mail, jogá-lo num pendrive, abri-lo num avião. Dê um duplo clique e ele simplesmente abre. Vamos ver exatamente como isso é possível daqui a pouco.
Pense nisso como… uma ótima exposição de museu. Nos bastidores houve meses de pesquisa bagunçada — escavações, discussões, becos sem saída. Mas o que você percorre é uma sala limpa e bem iluminada, com etiquetas claras, algumas coisas que você é convidado a tocar e um percurso que faz sentido. O visual-teach é o designer da exposição: ele pega a bagunça de um trabalho finalizado e monta uma sala onde você de fato consegue aprender. Onde a analogia falha: uma sala de museu fica fixa no lugar, enquanto esta exposição é um único arquivo que você pode levar no bolso.
O visual-teach é o estágio de entrega do loop engineering harness. Depois que uma execução converge — o "done-when" mensurável do escopo é cumprido e provado num limite real — o loop é obrigado a produzir um curso visual-teach como o entregável legível por humanos. Essa exigência é o Portão do Curso: convergência não é "o código passa", é "o código passa e existe um curso autossuficiente que o explica". O resultado e a explicação são entregues juntos.
Cada lição é um único documento .html com CSS inline, SVG inline e JavaScript inline, e zero requisições externas — sem CDN, sem web fonts, sem arquivos de imagem, sem analytics. O ganho prático é durabilidade: ele renderiza de forma idêntica a partir de file:// hoje e daqui a cinco anos, sobrevive a ser compactado em zip e enviado por e-mail, e não tem como quebrar porque alguma dependência remota mudou de lugar. O curso também é publicado em um gist privado (secret) para ter uma URL compartilhável, mas o arquivo em si nunca depende disso.
Abra a maioria das páginas web e, sem alarde, elas puxam dezenas de outras coisas da internet — fontes, imagens, código de outras empresas, rastreadores. Se qualquer uma dessas coisas some, a página quebra. Uma lição visual-teach se recusa a jogar esse jogo. As palavras, as cores, os diagramas e os pedacinhos interativos estão todos escritos dentro do único arquivo. Nada é buscado em lugar nenhum.
Essa escolha é o motivo pelo qual esta página continua funcionando não importa onde ela vá parar. Wi-Fi desligado? Ainda funciona. Salvou ela ano passado? Ainda funciona. Mandou para um colega que abre num notebook de trabalho bem travado? Ainda funciona. O arquivo é a exposição inteira, paredes e tudo — não um ingresso que só vale se o museu ainda estiver de pé.
Isso também mantém as coisas honestas. Como nada carrega de fora, o curso que você recebe é exatamente o curso que foi feito — não dá para alterá-lo silenciosamente depois, e não há nada observando você lê-lo.
Pense nisso como… um livro pop-up impresso versus um cartaz que só diz "escaneie este código para ver as figuras". O livro pop-up tem tudo encadernado nas suas páginas — abra em qualquer lugar e funciona. O cartaz é inútil no instante em que o link apodrece ou o sinal cai. O visual-teach sempre constrói o livro pop-up.
<!-- a visual-teach lesson, top to bottom --> <!doctype html> <html lang="en"> <head> <style> /* all the look & feel — inline */ </style> </head> <body> <!-- the words you read --> <svg> <!-- diagrams drawn right here, no image files --> </svg> <script> /* the clickable bits — inline */ </script> </body> </html> # nothing above ever reaches out to the internet.
Você não precisa acreditar na fé. Peça ao seu agente (ou faça você mesmo) um grep no arquivo pelas formas usuais de uma página carregar algo remoto — e não encontre nada:
# run from the course folder; expect NO matches grep -nE 'https?://|src=|@import|cdn|googleapis' lessons/0010-visual-teach.html # the only http(s) you may see are inside SVG xmlns="..." namespaces, # which are identifiers, not network fetches.
Ou abra o arquivo com sua rede desconectada, ou carregue-o e veja o painel de Rede do navegador permanecer vazio. As três são checagens de limite reais — exatamente o tipo de prova que o loop exige em vez de uma afirmação.
Cursos são feitos para serem lidos, às vezes por um bom tempo, então são vestidos com uma paleta calma quente-neutra: papel marfim suave, texto cor de tinta escura, e um único laranja-argila amigável usado com parcimônia para apontar as coisas que importam. A ideia é que pareça um bom livro, não um painel.
E viu aquele botão de lua no canto superior direito? Aperte-o. A página inteira desliza para o modo escuro — suave para os olhos à noite — e ele lembra da sua escolha na próxima vez que você abrir. Se o seu computador já estiver configurado para o escuro, a lição começa discretamente no escuro por conta própria, sem um flash claro. Você não configurou nada; o motor já traz isso embutido.
O propósito de todo esse capricho não é decoração. Uma página agradável e legível é uma página que você de fato vai terminar. Conforto faz parte de ensinar.
Pense nisso como… um abajur de cabeceira com dimmer. O mesmo quarto, o mesmo livro — mas você pode baixar a luz para uma leitura noturna, e o abajur lembra onde você deixou o botão. Ninguém deveria ter que reajustar o clima toda vez que pega o livro.
Toda cor é uma custom property de CSS (um "token") em :root — --ivory, --slate, --clay, e assim por diante. O modo escuro é um único bloco de sobrescrita, :root[data-theme="dark"]{…}, que reaponta esses mesmos tokens para valores escuros. Como nada na lição fixa um valor hex de cor — tudo lê um token — virar um único atributo no <html> reskinniza a página inteira de graça. Novos componentes herdam o modo escuro automaticamente, contanto que usem apenas tokens.
Um pequeno script no <head> roda antes de a página pintar: ele lê a escolha salva no localStorage (caindo para o prefers-color-scheme do sistema operacional) e define data-theme imediatamente, de modo que um leitor no escuro nunca veja um flash branco. O botão de alternância apenas troca esse atributo e grava o novo valor de volta no localStorage. Esse mecanismo exato faz parte da casca compartilhada, idêntico em todas as lições.
Um curso são muitas lições, e todas precisam parecer uma coisa só. O visual-teach garante isso com uma regra esperta, quase teimosa: toda lição compartilha uma casca idêntica. A casca é a moldura ao redor do conteúdo — a paleta de cores, a barra de topo com a alternância de tema e o seletor EN/PT, o menuzinho "Nesta página", os botões de anterior/próximo lá embaixo. Essa moldura é escrita uma vez e depois copiada, caractere por caractere, em cada uma das lições.
"Caractere por caractere" não é força de expressão. A parte compartilhada de cada lição é obrigada a ser byte a byte idêntica a um template mestre. Se até mesmo um espaço escorregar, uma checagem automatizada falha e a lição é devolvida. Só o ensino de verdade — as palavras desta lição, seus diagramas, sua demo — pode diferir.
O ganho é uma sensação que você talvez nem perceba: você nunca tem que reaprender a mobília. O botão escuro está sempre no mesmo lugar, o botão de próximo sempre se comporta do mesmo jeito, o menu sempre tem a mesma cara. Sua atenção fica nas ideias, porque a sala nunca se rearranja entre as lições.
Pense nisso como… uma rede de hotéis bem administrada. Entre em qualquer filial e o interruptor está perto da porta, a chaleira está sobre a mesa, as toalhas estão no banheiro. A vista da janela muda de cidade para cidade — isso é o conteúdo da lição — mas o layout do quarto é deliberadamente o mesmo, para que você nunca procure o interruptor no escuro. A regra do byte a byte idêntico é a planta da rede, cumprida ao milímetro.
No código-fonte, a região compartilhada é cercada por marcadores de comentário — BEGIN SHARED SHELL / END SHARED SHELL para o CSS, mais os blocos cercados correspondentes para a stepbar, a wiznav, o footer e o <script> final da casca. Um build constrói uma lição copiando o template e editando apenas fora dessas cercas: o <title>, o rótulo do passo, o <h1> e o corpo entre a stepbar e a wiznav. Os bytes cercados nunca são tocados.
Um passo de verificação extrai a região compartilhada da lição e do template e os compara — se os bytes diferem, o portão falha e a lição não é entregue. Este é um exemplo literal do Portão da Prova do loop aplicado ao próprio curso: "casca compartilhada inalterada" não é afirmado pelo autor, é checado num limite real (um diff de bytes), a mesma disciplina sobre a qual todo este suite roda.
As pessoas chegam a um tema vindas de lugares diferentes, então cada lição é escrita em duas profundidades ao mesmo tempo. A versão simples — a parte que você está lendo — conta a história inteira em palavras do dia a dia, do começo ao fim. Você pode ler só isto e sair entendendo o tema de verdade; nada essencial fica escondido de você. Depois, guardada atrás de cada botão "Mostrar o detalhe técnico", há uma camada mais funda com os nomes precisos, os comandos exatos, os casos extremos. Abra se quiser; ignore se não quiser. Qualquer caminho é completo.
Essa é a regra que o motor faz cumprir: a camada simples tem que se sustentar sozinha. O painel técnico acrescenta precisão para os curiosos — ele nunca é onde o ponto de verdade está guardado. Você nunca deveria ter que abrir um painel só para acompanhar.
Cada lição também é entregue em dois idiomas: inglês e português brasileiro, lado a lado, com o seletor EN/PT no topo da página. Só a prosa é traduzida — os comandos, nomes de arquivo e código ficam exatamente como estão, porque eles são os mesmos em qualquer idioma e mudá-los iria quebrá-los.
Pense nisso como… uma trilha na natureza com dois tipos de placa. A placa grande e amigável conta a história inteira da floresta num parágrafo que qualquer um consegue ler. Ao lado, uma plaquinha acrescenta os nomes das espécies em latim e a química do solo para os botânicos. Você faz a caminhada completa só com as placas grandes — e a trilha está sinalizada nos dois idiomas para que mais gente possa percorrê-la.
Formalmente: o bloco .simple de cada seção é obrigado a transmitir o ponto completo da seção sem referência ao seu painel .technical. A alternância usa aria-expanded no botão e uma classe .open no painel, e há um controle "Expandir todo o detalhe técnico" para os leitores que querem a passagem densa. A camada .technical carrega jargão, flags exatas e modos de falha — precisão aditiva, nunca significado essencial.
O build PT-BR é um arquivo paralelo sob pt/lessons/ com <html lang="pt-BR">, o .cur virado no seletor de idioma e a profundidade dos links relativos ajustada. A regra de tradução é estrita: só a prosa. Código, comandos, caminhos de arquivo e identificadores são copiados ao pé da letra — traduzir grep ou um nome de arquivo quebraria o exemplo silenciosamente. A casca compartilhada permanece byte a byte idêntica entre os idiomas também.
Ler sobre uma coisa é um tipo de aprendizado; cutucá-la é outro. O visual-teach constrói pedacinhos interativos direto na lição para que você possa fazer o segundo tipo. Aqui está um, retirado direto da própria biblioteca de demos do motor — o tipo de widget que ele consegue encaixar em qualquer curso.
O tema que ele ensina é pequeno e concreto de propósito: um único botão vem em algumas variantes (forte, discreta, quase invisível, vermelho-perigo) e alguns tamanhos. A grade abaixo mostra cada combinação como um botão real, clicável — não uma foto de um. Abaixo da grade, escolha um tamanho e veja cada exemplo redimensionar de uma vez, e passe o mouse sobre um cartão para ver a sua linha correspondente na grade se acender. Esta é uma demo rodando ao vivo, dentro do mesmo arquivo único, sem internet.
Pense nisso como… a parede de amostras de uma loja de tintas, onde você pode trocar a mesma amostra entre acabamentos e tamanhos em vez de apertar os olhos num catálogo. Experimentar é melhor que ler sobre.
Cada linha é uma variante, cada coluna é um tamanho. Cada célula é o .l10cv_btn real e ao vivo que a demo renderiza.
| variante \ tamanho | sm | md | lg |
|---|---|---|---|
| primary | |||
| secondary | |||
| ghost | |||
| danger |
A matriz mostra como cada uma se parece; estes cartões dizem quando recorrer a cada uma. Escolha um tamanho para pré-visualizar cada variante naquele tamanho; passe o mouse sobre um cartão para acender a sua linha acima.
primary
A única ação principal da tela. Preenchida e chamativa para que o olho pouse nela primeiro.
Evite: duas primárias brigando numa mesma visão.
secondary
A ação de apoio ao lado da primária — "Cancelar", "Voltar". Contornada, mais discreta.
Evite: usá-la para a ação que você de fato quer que seja clicada.
ghost
A opção de baixa prioridade — "Pular", ícones de barra de ferramentas. Quase invisível até receber o mouse.
Evite: numa ação crítica ou destrutiva (fácil demais de não notar).
danger
A ação destrutiva — excluir, remover, revogar. Vermelho mais um verbo claro mais um passo de confirmação.
Evite: vermelho sozinho com texto vago como "OK".
O botão recebe dois eixos ortogonais: variant (cor/ênfase) e size (padding/font-size). Eles se compõem, então uma grade 4×3 vem de 4 + 3 = 7 regras de CSS, não 12 botões sob medida. O seletor de tamanho troca apenas a classe de tamanho em cada botão da demo em tempo de execução — prova ao vivo de que os eixos são independentes.
/* base + two independent axes (namespaced for this lesson) */ .l10cv_btn { font-weight:600; border-radius:8px; border:1.5px solid transparent; } .l10cv_btn.sm { font-size:13px; padding:7px 13px; } .l10cv_btn.lg { font-size:17px; padding:13px 24px; } .l10cv_btn.primary { background:#D97757; color:#fff; } .l10cv_btn.danger { background:#B04A3F; color:#fff; }
Este widget foi copiado ao pé da letra do exemplar de demo do motor 06-component-variants, e então cada id, classe e hook foi prefixado com l10cv_ para que ele não possa colidir com a casca compartilhada ou com qualquer outra demo no arquivo. Retirar e dar namespace é exatamente como o visual-teach reutiliza seus ~20 tipos de demo entre cursos sem que dois widgets jamais pisem um no outro.
Um curso inteiro não é escrito num único arroubo heroico. Ele é construído do mesmo jeito paciente com que o loop constrói qualquer coisa: uma lição por passo. O motor aprende o tema, rascunha uma única lição, a checa, a melhora e só então passa para a próxima. Esta própria lição foi um desses passos. Construir de forma incremental significa que um problema numa lição nunca afunda o curso inteiro.
E uma lição não está "pronta" só porque ela existe. Antes de ser entregue, ela tem que passar por uma checklist curta — quatro perguntas simples que o motor se recusa a pular:
Só quando as quatro passam é que a lição conta. Empilhe lições aprovadas o bastante e o próprio curso cruza a linha de chegada — o momento em que o loop diz "pronto" e te entrega o resultado na forma deste curso. Esse repasse tem um nome que vamos conhecer a seguir: o Portão de Publicação, onde o curso finalizado é colocado em algum lugar onde você pode compartilhá-lo.
Pense nisso como… um chef montando um prato de cada vez, e um balcão de passagem no fim: nada sai até passar pela linha — prato certo, ingredientes de verdade, com boa aparência, pronto para servir. Empilhe pratos aprovados o bastante e o banquete inteiro está pronto.
Para o humano
O curso é o seu entregável. É a coisa legível que você guarda no fim — a parte feita para que uma pessoa de fato entenda o que a execução fez, não apenas que ela terminou.
Para o modelo (LLM)
Construa de forma incremental — uma lição por passo — e passe pelos portões de Missão, Fontes, Demo e Entrega em cada uma antes de seguir adiante. Nenhuma lição é entregue com base numa afirmação.
Para o agente
O curso é totalmente autossuficiente: ele abre a partir de file:// com zero requisições externas, então pode ser verificado, compactado e repassado em qualquer lugar sem quebrar.
Portão da Missão: a lição ensina seu tema declarado com o padrão Simples→Técnico e uma camada simples autocompleta. Portão das Fontes: as afirmações rastreiam até artefatos ou evidências reais (fatos da web via o CLI Bright Data, nunca memória). Portão da Demo: ≥1 widget interativo inline funcionando e ≥1 SVG inline, zero recursos externos. Portão da Entrega: abre de forma autônoma a partir de file://, casca compartilhada byte a byte idêntica ao template, links de navegação e de idioma corretos. Uma lição que falha em qualquer portão é devolvida, não entregue.
No nível da execução, o Portão do Curso torna um curso visual-teach uma precondição da convergência: o loop não entregou até o curso existir ao lado do resultado provado. O Portão de Publicação (próxima lição) então publica esse curso em um gist privado/secret via um passo de achatar-e-reescrever para que ele tenha uma URL compartilhável, enquanto o próprio diretório course/ do repositório permanece a casa canônica.
Nada disso é conversa fiada — são arquivos reais no disco. Um curso mora numa pasta. Há um template mestre (a casca de onde cada lição é copiada), uma pasta lessons com os arquivos em inglês, uma pasta pt paralela para os em português, uma biblioteca de demos de onde os pedacinhos interativos são retirados, uma página de index que amarra as lições, e uma gallery dos tipos de demo. Esta lição é um arquivo naquela pasta lessons.
Você pode ver tudo isso. O bloco abaixo é o formato real da pasta do curso que produziu esta página, e há uma linha única que você pode rodar para listá-la você mesmo.
courses/harness/ ├─ _TEMPLATE-en.html # the byte-identical shell, EN ├─ _TEMPLATE-pt.html # the shell, PT-BR ├─ index.html # course home, ties lessons together ├─ gallery.html # the demo-type gallery ├─ lessons/ │ ├─ 0009-tools.html │ ├─ 0010-visual-teach.html # ← you are here │ └─ 0011-publish.html ├─ pt/lessons/ # parallel PT-BR lessons └─ demos/ └─ 06-component-variants.html # the demo lifted above
# see the whole course tree ls -R courses/harness/ # open this very lesson straight from disk — no server needed open courses/harness/lessons/0010-visual-teach.html
Uma lição é produzida copiando o _TEMPLATE-en.html e editando apenas as regiões fora da casca. Na convergência, o passo de publicação roda publish-course-gist.js sobre o diretório do curso — ele achata a árvore em nomes de arquivo únicos, reescreve os links internos e cria um gist secret para que o curso abra como um pacote navegável. Essa única ação para fora é o Portão de Publicação da próxima lição; o diretório course/ no repositório permanece a fonte canônica.
Cinco perguntas rápidas. Escolha uma resposta para ver por que ela está certa — recuperar bate reler.
Q1Qual é o entregável que o visual-teach produz ao final de uma execução do loop?
Q2Por que uma lição visual-teach continua funcionando com a internet desligada?
Q3O que a regra da "casca compartilhada byte a byte idêntica" garante?
Q4O que a camada Simples de uma seção precisa fazer?
Q5Qual portão torna um curso visual-teach uma precondição para uma execução estar "pronta"?
Conclusão
O visual-teach transforma uma execução finalizada em um único curso HTML autossuficiente: acolhedor e legível com modo escuro, construído sobre uma casca byte a byte idêntica, com SVG inline e demos clicáveis, escrito Simples→Técnico em EN + PT-BR. O humano recebe um entregável que de fato entende; o modelo o constrói uma lição por passo com portões checados; o agente entrega um arquivo que abre em qualquer lugar a partir de file://.
grep neste arquivo por qualquer fetch https:// e não achar nenhum, para te mostrar os marcadores BEGIN SHARED SHELL, ou para abrir a demo em demos/06-component-variants.html. A seguir, acompanhamos o curso finalizado saindo porta afora: O Portão de Publicação.