O que UltraExplainer faz?
Transforme código, sistemas, diffs, planos, dados e conceitos em uma única página HTML autocontida que torna a ideia importante óbvia na primeira tela — e a comprova com evidências ancoradas. UltraExplainer é três coisas trabalhando juntas:
- Um método de síntese (o cérebro) — como decidir o que mostrar, o que enfatizar, o que cortar e como nunca desenhar uma estrutura que não está na fonte. Consulte
references/synthesis-method.md. - O estúdio camaleão (o artesanato) — um contrato de componentes estável e agnóstico a linguagens de design (
assets/core.css) reestilizado por sete linguagens de design completas (assets/themes.css). O mesmo diff renderiza como uma gutter de IDE no Terminal, um callout pautado no Blueprint, uma figura no Editorial. Você escolhe a linguagem para se adequar ao assunto; brilho é uma opção (Luminous), nunca o padrão. Consultereferences/aesthetic-languages.mdereferences/component-contract.md. - Uma camada de interatividade (
assets/ux.js) — um mecanismo compartilhado estado→renderização que alimenta sliders, toggles de cenários, passos passo a passo, tabelas ordenáveis/filtráveis, navegação scroll-spy e gráficos de nós e arestas roteados. Consultereferences/interactivity.md.
Identidade: verdade + a linguagem de design certa + artesanato verificado. Não "tudo brilha", não "sopa de caixas e setas", não "uma parede de cartões idênticos".
Quando usar esta skill
Recorra a uma página HTML sempre que a saída for inerentemente visual, relacional ou manipulável e ASCII/Markdown a distorceria:
- Um diagrama, visão geral de arquitetura ou gráfico de nós e arestas de como algo se conecta ou flui.
- Um diff / revisão de PR (código alterado + por que importa + raio de impacto).
- Um plano / auditoria de requisitos ou matriz de comparação.
- Um dashboard de métricas, ou qualquer tabela com 4+ linhas / 3+ colunas.
- Um explicador de conceito que ensina um mecanismo, ou um modelo interativo que o leitor deve sentir alterando uma entrada.
- Uma apresentação de slides, ou um resumo de projeto para troca de contexto.
Se a resposta honesta couber em uma frase ou um único número, diga-a no chat — não fabrique uma página (a regra do explicador mínimo viável). Quando construir, forneça um resumo de uma linha no chat e entregue o arquivo.
Dois modos — decida na carta
Declare em qual modo você está (para que o usuário possa corrigi-lo):
- EXPLAIN (padrão) — tese primeiro, para revisores / tomadores de decisão / trocadores de contexto que precisam da conclusão rapidamente. Limites de saliência se aplicam (T0 ≤ 3, T1 ≤ 7).
- TEACH — pergunta primeiro, para aprendizes que precisam de um modelo mental executável. Concreto antes de abstrato, prever-depois-revelar, termina com uma verificação de transferência. Consulte
references/teaching.md.
O método, em resumo
Leia references/synthesis-method.md antes de gerar algo não trivial. A forma resumida:
- Carta — uma frase: "Isto explica na altitude <A0–A4> para <público> para que eles possam ," mais o modo (EXPLAIN/TEACH). Mantenha uma altitude.
- Tese com tensão — uma afirmação declarativa que o leitor ainda não sabe (não um tópico). Escolha a espinha (o eixo único que o olho segue).
- Registro de evidências — leia a fonte real; para cada nó/aresta/rótulo/número registre
{afirmação, âncora (arquivo:linha / símbolo / ref git / métrica+data), confiança (verificado|inferido|assumido)}. Sem âncora → não renderiza como fato. Para modelos interativos, cada intervalo/padrão de slider e a função entrada→saída é ancorada ou carimbada "modelo ilustrativo, não medido". - Reconciliar — sustente a tese contra evidências contraditórias; revise, escope ou mostre-a. Nunca a descarte silenciosamente.
- Verificação mínima viável — não renderize demais. Resposta simples → frase herói + um visual.
- Hierarquia de saliência — T0 (tese + espinha, ≤3) / T1 (suporte estrutural, ≤7) / T2 (comprovantes, em
<details>/hover). Acima do limite → divida ou rebaixe, nunca encolha para caber. (Modo TEACH troca limites por um orçamento de dificuldade desejável.) - Escolha a linguagem de design — pontue as 7 linguagens em assunto × público × meio e registre uma linha:
LINGUAGEM: <nome> porque <assunto + público + meio>. Veja abaixo. - Represente — pergunte primeiro pela manipulabilidade ("o leitor deve sentir uma relação alterando uma entrada?"); se sim, recorra a um modelo/stepper/toggle de cenário. Caso contrário, escolha a forma estática de menor tinta. Codifique magnitude quantitativamente (tamanho/comprimento/posição), não caixas iguais.
- Comprima — omissão é o artesanato; colapse repetição ("×12 manipuladores"); extraia as linhas estruturais, não arquivos inteiros.
- Portões — passe em todos os três antes de entregar (abaixo).
Três portões de entrega — a verdade supera todos
- VERDADE — cada nó/aresta/número rastreia para uma âncora real; conteúdo inferido/assumido é visivelmente atenuado; a tese foi reconciliada contra evidências contraditórias; você reabriu as âncoras. Um "não pude confirmar X" claramente marcado supera uma fabricação confiante. Uma mentira interativa (um slider varrendo uma relação fabricada) é o pecado capital.
- ARTESANATO — o teste do apertar os olhos: de longe, lê-se como uma linguagem de design deliberada, não um template recolorido. Exatamente um ponto focal T0.
- OBSERVADO — você realmente renderizou a página e olhou. Construa-a, abra-a (captura de tela headless em ~1280 e ~360), capture erros de console, afirme que não há rolagem horizontal e que a tese está no primeiro viewport, então autocorrija. Pare de afirmar propriedades de checklist que você nunca mediu.
Como construir uma página (montagem)
As páginas são montadas por scripts/build.mjs a partir de um fragmento de corpo em templates/_src/<nome>.body.html. O caminho mais rápido: copie o template mais próximo, mude o preset e adapte o conteúdo.
- Diretiva da linha 1 (JSON em um comentário HTML) seleciona a linguagem e ajustes:
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset:blueprint | editorial | terminal | instrument | notebook | swiss | luminous(padrãoluminous)presets: ["…","…"]→ emite um arquivo por linguagem (demos camaleão)theme:light | dark(padrão é a afinidade natural do preset)fx:glow | flat(apenas Luminous)head/foot: marcação extra; sidecars<nome>.head.html/<nome>.foot.htmltambém são mesclados
- A build inlineia
core.css+themes.css+ux.js, vincula as fontes do preset, definedata-theme-preset/data-theme/data-fxantes da pintura (livre de FOUC), e emitetemplates/<nome>.html. - Execute:
node scripts/build.mjs <filtro-nome>(filtro é uma substring; omita para construir todos). - As únicas requisições externas da página são Google Fonts (com fallbacks do sistema — o layout nunca depende delas) e, para páginas Mermaid, o CDN do Mermaid. Deve continuar com boa aparência se falharem.
CRÍTICO ao inlinear qualquer JS que contenha a string literal
</script>(ex.: um snippet de exemplo): escape-a como</script>ou ela fecha a tag prematuramente e despeja fonte na página.
Escolhendo a linguagem de design
Roteie com base nos méritos, registre o motivo. Scorecard completo + perfis por linguagem em references/aesthetic-languages.md.
| Assunto | Linguagem padrão |
|---|---|
| Arquitetura, esquemas, protocolos, topologia de infra | Blueprint |
| Conceitos, ADRs, post-mortems, narrativas executivas | Editorial |
| Diffs, PRs, ferramentas CLI, pipelines de CI, logs | Terminal |
| Métricas, benchmarks, auditorias, dashboards | Instrument |
| Ensino, walkthroughs, onboarding, explicadores suaves | Notebook |
| Comparações, páginas de princípios/manifestos, relatórios de status | Swiss |
| Demonstrações de fluxo de sistema, visão de produto, briefs de fator uau | Luminous (nunca por padrão) |
Desempates: honre solicitações explícitas do usuário ("faça ser um terminal"); alterne para evitar monotonia na sessão; nunca escolha Luminous apenas porque é chamativo.
Escolhendo a representação
Roteie com base no trabalho cognitivo e na forma dos dados, não no tipo de conteúdo. Manipulabilidade primeiro. Catálogo completo + roteamento em references/representations.md; gráficos honestos em references/charts-honesty.md.
| Trabalho | Representação (componente) |
|---|---|
| Uma conclusão dominante / sim-não | Herói de tese tipográfica (.ux-thesis), talvez um visual abaixo |
| O leitor deve sentir uma relação | Modelo de parâmetros ([data-playground]) — sliders + leituras vinculadas |
| Ordem / estado intermediário é o significado | Passo a passo ([data-stepper]) — código↔dados em sincronia |
| Comporta-se de forma diferente entre configurações | Toggle de cenário (.ux-seg[data-scenario-ctl]) reilumina um diagrama |
| Sequência linear verdadeira | Lista numerada / faixa de fluxo (.ux-spine) — não um fluxograma |
| Ramificação / mesclagem / fluxo cíclico | Gráfico de nós e arestas (.ux-graph, ≤12 nós) ou Mermaid temático |
| Relações pareadas densas | Mapa de calor matricial (.ux-matrix) — supera um gráfico de cabelo |
| Mudança de código / PR | Diff anotado + veredito (.ux-diff + .ux-verdict) + raio de impacto |
| Conceito / conceito errado | Painéis ingênuo-vs-correto (.ux-compare) + um exemplo trabalhado |
| Comparação / auditoria / matriz | Tabela ordenável e filtrável (.ux-table, th[data-sort], data-ux-filter) |
| Métricas quantitativas | Linha de KPIs com delta (.ux-kpis) + gráfico honesto mais enxuto (.ux-bars/.ux-linechart) |
| Plano / roadmap | Bloco atual→alvo + linha do tempo com riscos hierarquizados (.ux-timeline) |
| Apresentação | Deck de slides (templates/slides) |
| Nada se encaixa | SVG inline personalizado usando tokens do tema |
Templates (templates/, com fontes em templates/_src/)
| Template | Linguagem | Demonstra |
|---|---|---|
chameleon.<preset>.html | todas as 7 | a MESMA explicação renderizada em cada linguagem — o teste do apertar os olhos |
blueprint → playground | Blueprint | modelo orientado por parâmetros (sliders, KPIs/barras vinculados, predefinições) |
terminal-diff | Terminal | revisão de PR: diff anotado + veredito + raio de impacto |
instrument-dashboard | Instrument | cabeçalho de KPIs + gráficos de linha/barra honestos + tabela ordenável/filtrável |
editorial-concept | Editorial | explicador de conceito: navegação scroll-spy + SVG personalizado + ingênuo-vs-correto + notas laterais |
notebook-teach | Notebook | modo TEACH: passo a passo + prever-depois-revelar + verificação de transferência |
swiss-comparison | Swiss | matriz de decisão: numerais oversized + tabela de comparação ordenável |
luminous-flow | Luminous | toggle de cenário (acerto/erro) + gráfico roteado + brilho opcional |
mermaid | qualquer | Mermaid temático com zoom/pan/expandir |
slides | qualquer | deck em viewport cheio com navegação por teclado/scroll |
Roteamento de referências — leia apenas o que a saída atual precisa
| Necessidade | Leia |
|---|---|
| Como decidir o que/como mostrar (o cérebro) | references/synthesis-method.md |
| As 7 linguagens, scorecard de seleção, teste do apertar os olhos | references/aesthetic-languages.md |
Camadas de tokens, cada componente .ux-, build/montagem | references/component-contract.md |
| Catálogo de representações + roteamento forma-de-dados × trabalho | references/representations.md |
| Sliders, toggles de cenário, steppers, gráficos, scroll-spy — a API JS | references/interactivity.md |
| Gráficos honestos: registro de números, hierarquia de canais, regras de eixos | references/charts-honesty.md |
| Modo TEACH: estado do aprendiz, concreto primeiro, prever-revelar, transferência | references/teaching.md |
| Manuais por trabalho (revisão de PR, postmortem, ADR, perfil de desempenho, …) | references/playbooks.md |
| Autocontenção, segurança de estouro, ciclo de verificação, checklist de entrega | references/self-contained.md |
| Mermaid temático (quando + como) | references/mermaid.md |
| Decks de slides | references/slides.md |
Invariantes
- A verdade supera a beleza e o artesanato. Ancore ou omita; atenue conteúdo inferido/assumido; nunca invente camadas, simetria, arestas ou justificativas. Intervalos/funções interativas são ancorados ou carimbados "modelo ilustrativo".
- Uma linguagem por página, escolhida com base nos méritos e registrada. Deve passar no teste do apertar os olhos. Brilho é exclusivo do Luminous, roteado através de
--fx-*para quedata-fx="flat"o remova completamente; sem respiração/pulsão contínua em conteúdo estático. - Sem rolagem horizontal na página.
min-width:0em filhos de grid/flex; conteúdo largo (diffs, tabelas, Mermaid) rola dentro de seu próprio containeroverflow-x:auto. Verifique em 360px. - Ambos os temas parecem compostos. Claro é reajustado, não invertido. A página abre em seu tema escolhido e o leitor pode alternar (persistido por preset); respeite
prefers-reduced-motion; mantenha o foco do teclado visível; seguro para impressão. - Componentes consomem apenas tokens semânticos +
--fx-*— nunca hex. Novas aparências vêm de pacotes de tema, não de cores inline. - Nunca defina uma classe
.nodeno nível da página — Mermaid a usa internamente. Todas as classes do UltraExplainer são prefixadas com.ux-. - Observe antes de entregar. Renderize a página, olhe para ela, corrija o que está errado. Não afirme o que você não mediu.
Checklist final
Documento autocontido no caminho correto · construído com o preset escolhido · sem erros de console · sem estouro horizontal em desktop ou 360px · fontes degradam graciosamente · a tese é óbvia no primeiro viewport com exatamente um ponto focal · tabelas/diffs/diagramas rolam dentro de seus próprios containers · toggles de tema (e brilho Luminous) funcionam · cada afirmação ancorada ou atenuada · a página foi realmente renderizada e inspecionada.