@andespindola/crow-skills 0.41.0 → 0.42.0

package/skills/crow-design/references/tipografia.md

@@ -0,0 +1,139 @@
+<!-- Derivado de Impeccable (Apache-2.0, Paul Bakaus), design-taste-frontend e high-end-visual-design (MIT, Leonxlnx), design-system (MIT, claudekit) e platform-design-skills (MIT, ehmo); reescrito e modificado pelo Crow em 2026-11-13. Ver ../NOTICE.md. -->
+# Tipografia
+
+Leia quando o contrato for fixar famílias, papéis, escala, medida, peso, tracking, entrega de fontes, tipografia em scripts não latinos ou a tipografia nativa de iOS e Android.
+
+## Papéis
+
+Uma ou duas famílias, cada uma com papel declarado:
+
+- **Display:** títulos de hero e de seção, números de destaque. É onde a voz aparece.
+- **Texto:** corpo, rótulos, controles, ajuda. É onde a leitura acontece; legibilidade vence personalidade.
+- **Dado tabular:** números em coluna, preços, métricas. Usa a família de texto com `font-variant-numeric: tabular-nums`, não uma monoespaçada.
+- **Código:** trechos de código, IDs, hashes, chaves, medidas que precisam de colunas de caracteres. Aqui a monoespaçada é função, não fantasia.
+
+Duas famílias que não se distinguem a olho nu são uma família com custo dobrado. Os papéis viram tokens compostos (`display`, `heading`, `body`, `label`, `caption`, `code`) com família, tamanho, entrelinha, peso, tracking e `font-feature-settings`, para que nenhuma tela recombine esses valores à mão (ver [sistema de tokens](sistema-de-tokens.md)).
+
+## Escolha da face
+
+**Marca primeiro.** A fonte da marca é sempre permitida e zera qualquer lista de "evite" para os próprios ativos. Sem marca, a face é escolhida como um objeto do mundo do assunto: o que ela lembra, de onde vem, que época e que ofício carrega. Associação rasa de assunto não justifica escolha ("livro pede serifa", "tecnologia pede monoespaçada"); é o default vestido com a roupa do tema.
+
+**O modo pesa:**
+
+- **Operar e Ler** aceitam a pilha do sistema (`system-ui` e equivalentes) e fontes utilitárias. A tarefa é ler e agir sem atrito; uma face com muita personalidade no corpo de uma ferramenta cansa. Uma família costuma bastar.
+- **Persuadir e Experienciar** pedem uma face com ponto de vista, pelo menos no display.
+
+**Face do sistema não é voz display.** Impact, Arial Black ou a sem serifa da plataforma como voz de título numa página com mundo próprio não serve: escolha uma face cujo caráter corresponda e hospede-a no projeto. Monoespaçada usada para "parecer técnico" é fantasia, não sistema.
+
+**Ênfase dentro da mesma família:** itálico ou negrito da própria família. Injetar uma palavra serifada (muitas vezes em itálico) num título sem serifa é truque de template, não hierarquia.
+
+### Licença declarada
+
+Toda família no contrato carrega sua licença:
+
+- **Livres (OFL ou equivalente):** podem ser hospedadas e distribuídas no projeto.
+- **Gratuitas com termos próprios (Fontshare e similares):** uso permitido dentro dos termos da distribuidora; leia-os antes de embutir em app ou produto vendido.
+- **Comerciais:** entram só quando o dono confirma a licença para o uso real (web, app, número de visualizações). Sem confirmação, o contrato nomeia um **equivalente livre** como fallback.
+
+Nunca "assumir que está disponível": presumir uma fonte comercial quebra o build quando o arquivo não existe e pode violar licença quando existe. As licenças abaixo são a classificação usual; confirme na foundry antes de fixar.
+
+### Não escolha por reflexo
+
+Estas famílias aparecem em quase toda interface gerada e, por isso, não dizem nada sobre o assunto: Fraunces, Instrument Serif, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter (como display e como default não pensado), DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans, e Roboto, Arial, Open Sans e Helvetica como escolha automática.
+
+A lista é default recusável, não proibição. Ela cede quando a família é a fonte da marca, quando o brief a nomeia, ou quando há uma razão que só ela atende; a razão fica registrada. Inter, Roboto e a pilha do sistema continuam corretas quando o pedido é neutro, quando o produto é denso e utilitário, em setor público e em acessibilidade crítica. O problema é a escolha não pensada, não a família.
+
+### Disciplina de serifa
+
+Serifa como display não é default. Entra quando o brief nomeia a serifa, ou quando a família estética é genuinamente editorial, de luxo, de publicação, manuscrito, herança ou vintage, com a justificativa escrita. Em dashboard e produto denso, serifa não entra no corpo, nos rótulos nem nos dados. Creme quente com serifa display de alto contraste e acento terracota é o cluster editorial genérico (ver [cor](cor.md)).
+
+### Pools curados, por classificação corrigida
+
+Pontos de partida, separados pela classificação real e pela licença. Listas de origem misturavam grotescas entre as serifas (Cardinal Grotesque, Söhne Breit Kursiv e NB Architekt são sem serifa); aqui elas estão no lugar certo. "Migra Sans" aparece citada como display sem serifa, mas sua existência não foi confirmada: confira antes de usar.
+
+| Classe | Livres (OFL) | Fontshare | Comerciais |
+|---|---|---|---|
+| Sem serifa de texto | Geist, Inter, Inter Tight, Manrope, Public Sans, Source Sans 3, Work Sans, IBM Plex Sans | Satoshi, General Sans | Söhne, ABC Diatype, GT America, GT Walsheim, PP Neue Montreal |
+| Sem serifa display | Geist (pesos display), Inter Display | Cabinet Grotesk, Clash Display | Söhne Breit, Söhne Breit Kursiv, Cardinal Grotesque, NB Architekt, Migra Sans (a confirmar) |
+| Serifa | EB Garamond, Cormorant Garamond, Playfair Display, Literata, Source Serif 4 | — | PP Editorial New, Editorial Old, Migra, GT Sectra Display, Tiempos Headline, Reckless Neue, Recoleta, Canela, Domaine Display, Schnyder, Saol Display, IvyPresto, Tobias, ITC Galliard |
+| Mono | Geist Mono, JetBrains Mono, IBM Plex Mono | — | — |
+
+Algumas livres (Cormorant, Playfair, IBM Plex, Inter) estão também na lista de reflexo: são boas faces, mas pedem razão.
+
+**Pares que costumam funcionar:** Geist com Geist Mono; Satoshi com JetBrains Mono; Cabinet Grotesk com Inter Tight; GT America com IBM Plex Mono. **Equivalentes livres** para quando a comercial não tem licença confirmada (aproximação de papel, não de desenho): Söhne ou GT America → Inter ou Public Sans; ABC Diatype → Geist; Tiempos → Source Serif 4 ou Literata; display serifado de alto contraste → Playfair Display com razão registrada.
+
+Variação existe só contra defaults genéricos: dentro da mesma marca, a mesma família pode e deve se repetir. Não há rodízio de fontes "entre projetos"; não existe memória confiável do projeto anterior.
+
+## Escala
+
+| Modo | Razão | Unidade |
+|---|---|---|
+| Operar e Ler | 1.125 a 1.2 | `rem` fixo; nada fluido |
+| Persuadir e Experienciar | 1.25 a 1.333 ou mais | corpo em `rem` fixo; só o display fluido com `clamp()` |
+
+O display fluido usa `clamp(mínimo, valor-com-vw, máximo)` com mínimo e máximo em `rem`, para que o zoom continue funcionando; `vw` puro ignora o zoom do usuário. Tipografia fluida no corpo de uma ferramenta faz a mesma tela ter tamanhos diferentes em monitores diferentes, o que atrapalha a leitura de densidade.
+
+**Escala de referência** (base 16px), a ajustar à marca: 12, 14, 16, 18, 20, 24, 30, 36, 48, e degraus de display acima disso. Entrelinhas nomeadas: 1, 1.25, 1.375, 1.5, 1.625. Pesos: 400, 500, 600, 700, carregando só os usados.
+
+Degraus de tamanho e de peso precisam ser óbvios a olho nu; dois tamanhos a 1px de distância são ruído. Hierarquia também se faz com peso, cor e espaço, não só com tamanho: um H1 gigante não substitui estrutura. Para simplificar uma superfície: uma família, três ou quatro tamanhos, dois ou três pesos. Para acalmar uma superfície barulhenta, desça pesos (900 para 600, 700 para 500) antes de mexer em tamanho.
+
+**Display máximo de cerca de 6rem** como heurística: acima disso o título vira imagem e começa a brigar com o conteúdo. Cede quando o brief ou o mundo pedem (peça tipográfica, cartaz, Experienciar) e a decisão é registrada.
+
+## Medida, corpo e entrelinha
+
+- **Medida:** 45 a 75 caracteres por linha, alvo 60 a 70; contêiner de prosa em torno de 65ch. Abaixo de 45 a leitura vira zigue-zague; acima de 75 o olho se perde na volta. Tabelas densas podem passar de 120 caracteres quando o dado pede.
+- **Corpo na web:** 16px (1rem) ou mais. Texto secundário a partir de 14px. Input no celular com 16px ou mais: abaixo disso o Safari do iOS dá zoom ao focar.
+- **Entrelinha inversa à medida:** linha mais longa pede mais entrelinha (corpo em torno de 1.5 a 1.625); títulos grandes, menos (1 a 1.2). Texto claro sobre fundo escuro ganha um pouco mais de entrelinha, um pouco de tracking e às vezes um degrau de peso, porque a irradiação faz as letras parecerem mais finas e mais juntas.
+- **Parágrafos:** espaço entre parágrafos **ou** recuo de primeira linha, nunca os dois. Recuo combina com texto contínuo editorial; espaço, com interface.
+- **Quebra:** títulos com `text-wrap: balance`; parágrafos com `text-wrap: pretty` quando disponível, para evitar viúvas.
+- **Itálico com descendentes** (g, j, p, q, y) em display: entrelinha de pelo menos 1.1 e uma pequena folga inferior (da ordem de 4px de padding ou margem), senão as hastes são cortadas pelo contêiner seguinte.
+
+## Tracking
+
+- **Negativo só em display latino:** nunca abaixo de −0.04em; entre −0.02 e −0.03em costuma ler melhor. O utilitário "tighter" de algumas bibliotecas é −0.05em e fica abaixo do piso.
+- **Corpo:** tracking 0. Tamanhos pequenos (12px e abaixo) podem ganhar um pouco de tracking positivo.
+- **Caixa alta** pede tracking positivo (da ordem de 0.05 a 0.1em) e só existe em scripts com caixa. Rótulo em caixa alta com 10 ou 11px é ilegível para muita gente: rótulos ficam com 12px ou mais e contraste AA.
+- **Scripts sem caixa ou com letras ligadas** (CJK, árabe, devanágari): tracking 0, nem positivo nem negativo.
+
+## Títulos de hero e de seção
+
+- O título do hero cabe em até duas linhas no desktop. Quatro linhas é erro de tamanho de fonte, não de texto.
+- A maioria dos heros vive entre 36 e 60px (subindo com a largura); 60 a 72px só com títulos de três a cinco palavras; com mídia grande ao lado e mais de seis palavras, nada acima de 60px.
+- Os limites são de **medida visual** (linhas e largura), não de contagem de palavras: português e alemão crescem 30 a 40% em relação ao inglês, e o contrato precisa sobreviver à tradução.
+- Título quebrado à mão com `<br>` e a última palavra em itálico é tique de template; deixe a quebra para `text-wrap: balance`.
+
+## Números e recursos OpenType
+
+- `tabular-nums` em colunas, preços, contagens, métricas, placares e cronômetros (qualquer número que muda no lugar treme sem algarismos tabulares). Na tabela, números alinham à direita (ver [dados e densidade](dados-e-densidade.md)).
+- Algarismos de texto (`oldstyle-nums`) em prosa editorial quando a família oferece; frações (`diagonal-fractions`), zero cortado (`slashed-zero`) em IDs, ligaduras discricionárias só em display e com intenção. Confirme que a família tem o recurso antes de pedi-lo.
+
+## Entrega de fontes
+
+O contrato decide o que carregar; quem implementa decide como:
+
+- Só as famílias, pesos e estilos usados. Fonte variável quando ela substitui vários arquivos estáticos.
+- Fallback com métricas compatíveis (`size-adjust`, `ascent-override`, `descent-override`, `line-gap-override`) para reduzir o salto de layout quando a fonte chega.
+- `font-display: swap` para texto; `optional` quando o fallback é aceitável e a estabilidade importa mais que a face.
+- **Subset sem cortar o idioma real:** `unicode-range` para português inclui Latin-1 Supplement e Latin Extended-A, não só o ASCII básico, senão os acentos caem no fallback e a palavra fica com duas faces. Idiomas não latinos ganham fallback do próprio script declarado.
+- **Preload só da face crítica** do primeiro viewport (em geral o display do hero e o peso regular do corpo).
+- **Hospedada no projeto** (self-host com `@font-face` ou o mecanismo de fontes do framework) em produção, em vez de link para serviço de fontes de terceiros: evita uma requisição bloqueante a outro domínio, a dependência de disponibilidade alheia e o envio de dados do visitante. Cede quando a licença só permite o serviço da foundry.
+
+## Scripts não latinos e RTL
+
+- **CJK:** entrelinha maior que a do latim (corpo da ordem de 1.7 a 1.8), sem itálico sintético (o navegador inclina o glifo, o que não existe nessas escritas), sem tracking, quebra de linha conforme as regras do idioma (`line-break`, `word-break: auto-phrase` onde houver suporte). Fallback com as fontes do sistema de cada idioma (japonês, chinês simplificado e tradicional e coreano têm faces diferentes).
+- **Árabe e outros scripts de letras ligadas:** sem tracking (separa as letras e quebra a escrita), sem caixa alta (não existe), entrelinha maior para acomodar ascendentes e descendentes altos, tamanho de corpo às vezes um degrau acima para a mesma legibilidade.
+- **RTL:** alinhamento por `start`/`end`, propriedades lógicas, ícones direcionais espelhados; números continuam da esquerda para a direita dentro do texto.
+- Tokens tipográficos por script, trocados com `:lang()`; o contrato prevê pseudo-localização quando há i18n (ver [adaptação](adaptacao.md)).
+
+## Zoom e escala do usuário
+
+- Texto em unidades relativas (`rem`), sem `maximum-scale=1` nem `user-scalable=no` no viewport.
+- Zoom de 200% sem perda de conteúdo nem de função; reflow em 320 CSS px de largura sem rolagem horizontal (exceto tabelas e mapas).
+- O layout sobrevive ao ajuste de espaçamento de texto do usuário: entrelinha 1.5, espaço de parágrafo 2× o tamanho, letra 0.12em e palavra 0.16em. Contêiner com altura fixa em volta de texto é o que corta.
+- Dynamic Type no iOS e escala de fonte (`sp`) no Android são respeitados até os maiores tamanhos.
+
+## Nativo
+
+**iOS.** A interface usa a família do sistema (SF Pro; SF Compact no relógio) e os estilos de texto do Dynamic Type, não tamanhos fixos. No tamanho padrão: Large Title 34, Title 1 28, Title 2 22, Title 3 20, Headline 17 semibold, Body 17, Callout 16, Subheadline 15, Footnote 13, Caption 1 12, Caption 2 11pt. O "piso de 11pt" e a regra "sem tamanhos fixos" convivem assim: 11pt é o menor estilo (Caption 2) no tamanho padrão, um limite para escolher estilos, não um número a escrever à mão; com Dynamic Type ele cresce como todos os outros. Fonte de marca entra escalada pelo estilo correspondente (relativa a um estilo de texto), nunca em pontos fixos.
+
+**Android.** Escala tipográfica do Material: Display, Headline, Title, Body e Label, cada um em L, M e S. Valores padrão da escala do Material 3, a conferir na versão adotada: Display 57/45/36, Headline 32/28/24, Title 22/16/14, Body 16/14/12, Label 14/12/11sp. Roboto ou a fonte da marca, sempre em `sp`, para que a escala de fonte do sistema (que pode passar de 200%) funcione. Layout que corta texto em escala grande é defeito, não caso extremo.