design-doc

Documento

Um documento é lido sequencialmente e impresso em papel. Ambos os fatos limitam o layout: uma única coluna de texto, quebras de página reais e nada que dependa de hover.

Decida a paginação primeiro

• Fluxo contínuo (padrão) — um fluxo de texto contínuo; o mecanismo de impressão do navegador o divide entre as páginas. Adequado para relatórios, memorandos, cartas, ensaios e qualquer coisa cujo comprimento você não controle.
• Páginas fixas — blocos explícitos <section class="page">, um por folha. Adequado quando a contagem de páginas é o design: um currículo de uma página, um folheto frente e verso, um certificado, um pôster.

Se a pessoa pediu "duas páginas", elas querem fixas. Se pediu "um relatório", querem fluxo contínuo. Quando não estiver claro, pergunte — construir a opção errada desperdiça o documento inteiro.

Geometria

Vincule o arquivo de tokens no <head>, além de components.css se o documento usar seus componentes, e use suas variáveis para cor, tipo e espaço. As regras abaixo são apenas de geometria do papel:

@page { size: A4; margin: 0; }        /* ou: size: letter; */
body  { margin: 0; background: white; }
.page { width: 210mm; min-height: 297mm; padding: 24mm 22mm; box-sizing: border-box; }
.page + .page { break-before: page; }

@media screen {
  body { background: gainsboro; padding: 32px 0; }
  .page { margin: 0 auto 24px; box-shadow: 0 2px 24px color-mix(in srgb, black 12%, transparent); }
}

Para documentos de fluxo contínuo, remova o .page fixo e defina @page { margin: 22mm } com uma coluna de max-width: 66ch. Tamanho do papel: A4, a menos que a pessoa seja claramente americana; nesse caso, Letter. Se eles informaram um tamanho, use o deles.

Tipografia

• Corpo 11–12pt, altura da linha 1.5–1.6. Nunca abaixo de 10.5pt para algo que precise ser lido.
• Medida de 60–75 caracteres. Mais largo que isso e o olho perde a linha.
• Uma família tipográfica para o corpo, opcionalmente uma segunda para os títulos. Mesmo pareamento do sistema de design, se houver.
• Títulos dimensionados por uma escala, com o título de nível superior visivelmente maior — 28–36pt — não 14pt negrito.
• Ênfase por peso e espaço, não apenas por cor. Um documento que imprime em escala de cinza ainda deve ser legível.

Estrutura

• Elementos semânticos reais: h1–h3, p, ul, table, figure, blockquote. Nada de divs estilizadas.
• Numeração de páginas via contadores @page se o documento tiver mais de duas páginas:

  @page { @bottom-center { content: counter(page); } }
  

  O suporte é parcial — um número no estilo nota de rodapé em cada página fixa é uma alternativa confiável.
• Tabelas: alinhe números à direita, texto à esquerda, use bordas finas em vez de bordas completas, repita o cabeçalho entre quebras com thead { display: table-header-group }.
• Evite break-inside: avoid em qualquer coisa mais alta que um terço da página.
• Figuras ganham legenda. Sem legenda, sem figura.

Conteúdo

Mantenha as palavras da pessoa. Você pode cortar e reordenar quando solicitado; não pode parafrasear. Se uma seção estiver vazia porque eles não a escreveram, deixe um espaço claramente marcado em vez de inventar texto.

Nada de fotografia de banco de imagens, nem de imagem gerada que seja apenas decoração. Quando o documento precisar de uma imagem real, gere-a com as ferramentas FLUX se estiverem disponíveis; caso contrário, use uma caixa de espaço reservado com uma nota monoespaçada dizendo o que pertence ali.

Finalização

Execute design-verify na largura de impressão e leia a captura de tela:

node ~/.config/opencode/lib/design/verify.mjs "design/Report.html" \
  --width 900 --height 1200 --full --out design/.verify/report.png

Verifique se há: texto cortado nas bordas da página, um título órfão no final de uma página, tabelas divididas incorretamente e qualquer estouro horizontal — que na impressão significa conteúdo perdido na borda direita.

Em seguida, imprima para PDF você mesmo uma vez (Cmd-P, Salvar como PDF) para confirmar a contagem de páginas e que nada se desloca no tamanho real do papel.