HTML View
node <skill-dir>/scripts/htmlview é o ponto de entrada de comando multiplataforma; doravante abreviado como htmlview. Requer Node.js 22+; a verificação no navegador, captura de tela, exportação e renderização de gráficos independentes também requerem Chrome ou Chromium. Se o navegador não for encontrado, siga o tratamento error.next.
HTML Existente: Apenas Trocar o Tema
- Produtos do htmlview: Para documentos, relatórios ou páginas de gráfico único, use
htmlview style file.html --theme cloudmusic(consultehtmlview style --listpara temas); para protótipos de interface, use--schemeou--brand. O comandostyleatualiza in-loco, apenas reestruturando o invólucro e os gráficos derivados. Para gerar um novo arquivo, primeiro copie para um nome de arquivo não utilizado no mesmo diretório, executestylena cópia e, em seguida, usehtmlview diffpara comparar o conteúdo. - HTML Comum:
stylenão aceita HTML comum. Se precisar usar o invólucro da skill, crie um novo documento temático (veja Fluxo de Documento e Componentes de Documento), migre o conteúdo existente para o novo arquivo; não reutilize o CSS e os scripts do invólucro antigo. Ao apenas alterar o estilo, mantenha os números originais, a granularidade temporal e as conclusões, não recalcule os dados nem perca detalhes dos gráficos originais para passar na verificação de exibição.
Escolha por Tarefa
| Resultado Desejado pelo Usuário | Ação | Quando Expandir |
|---|---|---|
| Planos técnicos, relatórios, instruções, atas ou resumos de uma página, fáceis de ler e anotar | Para Markdown, use doc build; para editar HTML diretamente, use doc new | Primeiro leia Fluxo de Documento; ao escrever componentes HTML manualmente, adicionar referências cruzadas ou manipular comentários, leia Componentes de Documento |
| Relatórios ou dashboards para verificar números de negócio, métricas e gráficos | Crie um pacote de dados a partir do arquivo de resumo upstream; após data validate, execute data build | Primeiro leia Fluxo de Relatório de Dados; ao modificar campos, métricas, gráficos ou narrativas, leia Pacote de Dados; para dashboards, leia Guia de Dashboard |
| Wireframes, protótipos de alta fidelidade ou maquetes para telas, estados ou fluxos de interação | Após ui new, preencha cada tela com controles reais e seus valores | Primeiro leia Fluxo de Protótipo de Interface; ao selecionar componentes ou escrever interações, leia Índice de Componentes; ao definir layout, esquema de cores ou escrever componentes manualmente, leia Guia de Design de Interface; ao desenhar painéis de dados, leia Guia de Dashboard |
| Gráfico SVG único ou página de gráfico off-line | Selecione a família de gráficos na tabela abaixo, escreva a declaração e então viz render | Para gráficos de dados, primeiro leia Regras Gerais de Declaração, depois a família selecionada; para diagramas estruturais, leia diretamente a família correspondente |
| Ler, inspecionar, capturar tela ou exportar HTML local | Use read, check, shot, export ou embed | Parâmetros e resultados de verificação em Exibição e Exportação |
- Quando o material não for uma estrutura de página pronta, como notas soltas, atas de reunião, JSON, CSV, logs, ou Markdown que precisa ser reorganizado, leia Do Material à Página antes de escrever o conteúdo.
- Os produtos HTML são arquivos únicos que podem ser abertos off-line. Ao escrever manualmente, modifique apenas o título e o conteúdo entre
<!-- htmlview:content -->e<!-- /htmlview:content -->; cada marcador é mantido uma vez. O layout, tema e scripts de execução são montados pela CLI. - Documentos construídos a partir de Markdown devem modificar a fonte Markdown; relatórios de dados devem modificar o pacote de dados, não o texto, gráficos ou números gerados diretamente. Dados sem fonte não devem ser inventados; dados de demonstração devem ser claramente identificados como exemplos fictícios.
- Para sobrescrever artefatos independentes existentes, confirme o destino antes de usar
--force; atualizações de documentos da mesma fonte não precisam de--force. - Quando
--langnão for passado, os comandos de geração inferem os termos do shell (números de figuras, sumário, legendas, etc.) a partir do título e do corpo: se a contagem de palavras em inglês for pelo menos o dobro da contagem de caracteres em chinês/japonês/coreano, use inglês; caso contrário, use chinês. Para outros idiomas ou conteúdo meio a meio, passe--langexplicitamente.
Escolha o Gráfico de Acordo com o que o Leitor Quer Ver
Use gráficos estáticos por padrão. Gráficos de dados usam KChart JSON; diagramas relacionais usam Mermaid ou declarações nativas. Primeiro consulte Regras Gerais de Configuração, Estilo, Links e Diagnóstico e, em seguida, o tipo de gráfico correspondente; KChart não copia a aparência do Mermaid. Preencha apenas dados, semântica e intenção de leitura, não escreva coordenadas, tamanhos de fonte, cores ou scripts de desenho. Gráficos podem ter rolagem interna; a página em si não deve transbordar horizontalmente.
| Pergunta do Leitor | Tipo de Gráfico | Leitura Sob Demanda |
|---|---|---|
| Como muda, quando muda? | line, area, sparkline, small-multiples, stream, combo, bump, candlestick, launch-fan | Tendências |
| Qual é maior, quanto falta, quão longe da meta? | bar, column, dumbbell, slope, bullet, gauge, interval, split-compare | Comparação |
| Como o todo é composto, quanto se perde em cada etapa? | share, pie, donut, radial-share, rose, funnel, waterfall, waffle, tally, treemap, sunburst | Composição |
| Como os valores se distribuem, há outliers ou correlação? | histogram, boxplot, violin, strip, scatter | Distribuição |
| Onde há anomalias em matrizes multidimensionais ou calendários? | heatmap, bubble-matrix, calendar, radar, parallel | Matriz |
| Quem está conectado a quem, como o volume flui? | network, sankey, threads | Rede |
| Onde estão distribuídos? | choropleth, geo-scatter | Mapas |
| Como classificar, como expandir a partir de um tópico? | KChart tree, mindmap; Mermaid mindmap, ishikawa, treeView-beta | Hierarquia e Mapas Mentais |
| Fluxo de quem para quem, como o estado transita? | flowchart, stateDiagram-v2, journey, swimlane-beta, eventmodeling, agentflow-beta, nativo swimlane | Fluxo |
| Qual é a ordem de chamada e quem são os participantes? | sequenceDiagram, usecase-beta | Sequência |
| Como agendar, dividir em colunas ou numerar? | gantt, timeline, gitGraph, kanban, packet, quadrantChart | Tempo e Grade |
| Como entidades, classes ou requisitos se relacionam? | erDiagram, classDiagram, requirementDiagram | Modelo de Dados |
| Como uma regra de sintaxe corresponde a símbolos? | railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta | Modelo de Dados |
| Como o sistema é estratificado, onde estão contêineres e dependências? | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment, architecture-beta, block, wardley-beta, nativo layers, blocks | Arquitetura |
| Visão geral de uma página: cartões em grupos, fluxo principal e legenda? | Nativo blocks (cartões, emblemas, legendas, linhas de destaque); block se já houver diagrama de blocos Mermaid | Arquitetura |
| Já tem gráficos de valor Mermaid? | pie, xychart, sankey, radar-beta, treemap | Gráficos de Valor Mermaid; para novos gráficos de dados, use os tipos KChart acima |
| Como os conjuntos se sobrepõem, como os cenários são categorizados? | venn-beta, cynefin-beta | Conjuntos, Cenários |
| Diagrama de chamada usando sintaxe ZenUML? | zenuml (Renderização nativa KChart, sem plugins externos) | ZenUML |
| Só quer confirmar a versão do renderizador? | Mermaid info (não para entrega) | Regras Gerais Mermaid |
Em Markdown, use cercas kchart, mermaid, layers, blocks, swimlane; em HTML escrito à mão, use <pre data-viz="syntax">, escapando caracteres especiais HTML. Os títulos das figuras em documentos são escritos na declaração: KChart title, no preâmbulo do diagrama estrutural title: ou na instrução de título suportada pela sintaxe. Os títulos das figuras e o texto dentro delas devem estar no mesmo idioma do corpo. Quando as famílias de gráficos internas não conseguem acomodar ou expressar, como aninhamento muito profundo, muitas relações ou diagramas de mecanismo, primeiro divida em um diagrama geral e sub-diagramas; se ainda precisar desenhar manualmente, leia SVG Personalizado.
Referência Rápida de Comandos
| O que fazer | Comando |
|---|---|
| Esboçar documento / gerar a partir da fonte | htmlview doc new plan.html --type plan --title 'Plano de Avaliação de Capacidade' ou htmlview doc build spec.md --out spec.html --type tech-spec |
| Pacote de dados e relatório | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| Esqueleto de protótipo de interface | htmlview ui new prototype.html --title 'Processamento de Solicitação' --device mobile --screens 'Lista,Detalhes' |
| Auditoria estática, comparar conteúdo | htmlview audit file.html; htmlview diff old.html new.html |
| Recarregar módulos de gráfico para documento ou protótipo | htmlview style file.html (mantém tema e conteúdo existentes) |
| Verificação de exibição, captura de tela, exportação | htmlview check file.html; htmlview shot file.html --select 'figure'; htmlview export file.html --format pdf; captura de página inteira htmlview export file.html --format png |
| Ler corpo, incorporar recursos locais | htmlview read file.html [--outline ou --section id]; htmlview embed file.html |
| Gráfico independente, restrições de campo, paleta de cores, medida de texto em gráfico manual | htmlview viz render spec.json --out chart.svg; htmlview viz schema bar; htmlview viz palette --theme paper; htmlview viz measure 'Serviço de Pedidos' --size 13 |
Quando o usuário fornecer seu próprio esquema de cores, use --theme-file <JSON>, campos e exemplos em Arquivo de Tema. O tema é embutido no HTML; protótipos de interface usam esquemas de cores de marca independentes.
htmlview <subcomando> --help fornece parâmetros precisos. Para comandos de verificação, pass:false significa que a verificação foi concluída, mas problemas foram encontrados; corrija conforme failures[].fix. ok:false significa que o comando não pôde ser concluído; siga o tratamento error.next.
Validar Antes de Entregar
- Após criar ou modificar um artefato, execute
audit. Se faltarem módulos de gráfico, executestylepara reestruturar e, em seguida, audite novamente; se o relatório tiver evidências inconsistentes, volte ao pacote de dados para corrigir. - Para alterações que afetam a exibição, execute
checke, em seguida,shotpara abrir a captura de tela real. Verifique a hierarquia de cabeçalhos, atribuição de texto, espaçamento em branco e a primeira tela em dispositivos móveis; para gráficos largos, abra o SVG completo para inspeção. Para protótipos interativos, percorra manualmente os caminhos críticos. - Ao entregar em PDF, abra o PDF real e verifique se os títulos e os gráficos estão na mesma página e se as bordas estão intactas. Se encontrar avisos de impressão, troque para um tamanho de papel adequado ou ajuste o layout, mantendo um tamanho de fonte legível; se não for possível imprimir completamente, documente as limitações.