hayatosc/html-artifacts

Artefatos HTML

Entregue um único arquivo .html voltado para humanos, que abra a partir do disco e funcione offline. Use o adaptador de documento do Sistema de Design da Agência Digital do Japão (DADS) disponível no repositório, e não um CDN ou framework. Mantenha o código-fonte voltado ao agente em Markdown. Este é um adaptador de documento não oficial, não uma implementação completa de todos os componentes do DADS.

Procedimento

1. Entenda o leitor e a fonte

Identifique o assunto, público, propósito e evidências antes de escolher a estrutura. Para planos, preserve objetivos, evidências de conclusão, restrições, pontos de verificação e riscos. Inclua um título descritivo, uma breve orientação e proveniência de fonte/data. Adicione um sumário apenas quando útil; não force um número de seções ou diagramas.

Explique a partir do zero: comece com uma situação concreta e o que o assunto faz, depois introduza nomes técnicos. Defina jargões no primeiro uso, dê a cada etapa uma ideia e use uma imagem legendada apenas quando ela explicar mais claramente que prosa. Use analogias apenas quando sua conexão e limites forem explícitos; mantenha um tom adulto e direto, a menos que esteja escrevendo para crianças. Um iniciante deve entender o que acontece, por que e o que fazer em seguida.

2. Construa mecanicamente — nunca redigite o CSS

Leia build.md. Resolva o diretório da habilidade a partir da localização deste arquivo, não do diretório de trabalho do projeto atual. Com Python 3.10+:

python /caminho/absoluto/para/html-artifacts/scripts/build.py /caminho/absoluto/para/saida.html --title "Assunto"

O construtor lê assets/template.html, incorpora todo o assets/dads.css e assets/print.js, e insere uma Política de Segurança de Conteúdo (CSP) offline. Ele se recusa a sobrescrever um arquivo existente. Nenhum download, instalação de pacote, servidor, bundler ou pasta de assets adjacente é necessário. Neste repositório, use seu executável Python (uv run python também funciona).

3. Edite o conteúdo, não a base

Edite o arquivo gerado. Substitua o conteúdo explicativo inicial, a proveniência e o sumário; remova seções desnecessárias. Mantenha intactos style#dads-css, script#dads-print, a CSP, charset, viewport e os metadados de only light color-scheme.

• Apenas SVG inline e imagens raster incorporadas. Nenhuma folha de estilo, script, fonte, imagem, iframe, import, fetch ou dependência de análise remota/local. Hiperlinks de fonte comuns podem apontar para a web; rotule arquivos de fonte locais como texto, em vez de links relativos quebrados.
• Use HTML semântico e as classes/tokens incluídos. Leia dads.md para a API de classes, fontes oficiais e adaptações locais. Não misture as APIs upstream data-type/data-size com os modificadores deste adaptador.
• Use diagrams.md antes de adicionar SVG. Dê a cada diagrama significativo um título, descrição, rótulos e uma alternativa textual. Coloque diagramas largos em uma região .dads-diagram-scroll rotulada e focalizável por teclado.
• Use fallbacks de fonte instalados; a falta de Noto não deve ocultar texto. Combine lang com o conteúdo. O corpo é 1rem/1.7 (16px na configuração padrão). Preserve o zoom do navegador e a refluência.
• Padrão para links e divulgações nativas. Mantenha as divulgações inicialmente open para que a impressão sem script retenha o conteúdo; o script incluído também abre qualquer divulgação colapsada pelo leitor para impressão e a restaura em seguida. Não adicione abas, botões inativos, JavaScript arbitrário ou atributos de manipulador de eventos.
• Permaneça claro em configurações escuras do SO: este adaptador não possui uma paleta escura oficial verificada. Não inverta apenas o fundo da página nem invente um conjunto de tokens escuros. Respeite cores forçadas e movimento reduzido.
• Prefira componentes existentes. Se essencial, coloque regras pequenas específicas do documento em um <style> inline separado; novas classes devem ser artifact-* e ter definições lá. Use tokens conhecidos, nunca os redefina nem altere o CSS incorporado. Verifique essas regras no navegador; validação estática não é um parser CSS ou auditoria de contraste.

4. Verificação final — corrija falhas antes da entrega

Execute após a última edição:

python /caminho/absoluto/para/html-artifacts/scripts/check.py /caminho/absoluto/para/saida.html

Em seguida, verifique o arquivo real em um navegador, com a rede desabilitada quando possível:

1. Conteúdo: prosa inicial/placeholders foram removidos; evidências solicitadas, fontes, datas e próximas ações permanecem. Leia as descrições dos diagramas independentemente; elas devem transmitir o significado.
2. Offline: sem requisições de recurso, assets com falha, violações de CSP ou erros no console. Hiperlinks de fonte são navegação, não dependências incorporadas.
3. Mobile/desktop: inspecione capturas de tela em 390px e 1280px; verifique adicionalmente a refluência a 320px/200% de tamanho de texto. Sem estouro horizontal em toda a página; apenas regiões de código/tabela/diagrama rotuladas e focalizáveis podem rolar. Inspecione caracteres japoneses reais e URLs longas.
4. Teclado/estados: siga o link de pular e o sumário, tabule para regiões de rolagem, alterne divulgações e inspecione foco visível e contraste de botão-link (incluindo visitado/hover). Nenhum significado apenas por cor.
5. Escuro/impressão: simule a preferência escura (a página deve permanecer legível clara), imprima com uma divulgação fechada, verifique se seu corpo imprime, e verifique tabelas/código largos e quebras de página. Preserve o conteúdo sem JavaScript deixando as divulgações inicialmente abertas.

O verificador aplica o contrato de assets/política incorporados, classes/tokens conhecidos e regras conservadoras de recursos offline. Ele não prova sintaxe CSS, layout, contraste, acessibilidade ou correção de HTML arbitrário. Se nenhum navegador estiver disponível, diga quais verificações visuais/interativas permanecem não verificadas; nunca afirme capturas de tela a partir apenas de verificações estáticas.

5. Entregue

Salve ao lado da fonte ou no diretório de trabalho, nomeado pelo assunto (PLANO.html para um plano). Retorne o link do artefato e limitações materiais, não uma cópia do documento ou uma segunda auto-auditoria genérica.

Para SSH/outro dispositivo, siga remote-preview.md. Um caminho remoto ou xdg-open não é uma entrega de visualização utilizável. Sirva apenas uma cópia isolada, use um túnel público apenas para conteúdo autorizado a compartilhamento público, caso contrário use encaminhamento SSH/controle de acesso, e forneça instruções de limpeza. Mantenha o HTML original seguro para uso offline.

Recursos

• assets/template.html, assets/dads.css, assets/print.js: fontes mecanicamente incorporadas.
• scripts/build.py, scripts/check.py: construção e verificação de contrato final usando a biblioteca padrão.
• build.md: padrões de edição e solução de problemas.
• dads.md: proveniência oficial, tokens, API de componentes do adaptador.
• diagrams.md: padrões de SVG inline legíveis.
• remote-preview.md: entrega remota segura.

A abordagem de explicar a partir do zero é inspirada pela habilidade ELI5.