@andespindola/crow-skills 0.41.0 → 0.42.0

package/skills/crow-design/references/sistema-de-tokens.md

@@ -0,0 +1,264 @@
+<!-- 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. -->
+# Sistema de tokens
+
+Leia quando o contrato precisar fixar valores: criar ou estender tokens, definir modos (claro, escuro, alto contraste), mapear para CSS ou Tailwind, exportar, versionar ou validar. O formato de referência é o [template de tokens](../templates/tokens.exemplo.json).
+
+## Três camadas
+
+- **Primitivo:** valores crus, sem significado de uso (`color.neutral.900`, `space.4`, `duration.200`). Nunca referencia outro token. Muda raramente: quando a marca muda ou uma rampa é corrigida.
+- **Semântico:** papéis (`surface.canvas`, `text.secondary`, `action.primary.bg`, `focus.ring`). Referencia só primitivos. É a camada que os modos sobrescrevem; trocar de tema é remapear semânticos.
+- **Componente:** decisões de um componente (`button.primary.bg`, `input.border`). Referencia semânticos. Existe quando o componente precisa de um ponto de customização próprio; não se cria token de componente por reflexo.
+
+Código de interface consome semântico ou componente, nunca primitivo nem valor literal. Um componente que pula a camada semântica (`card.bg` apontando direto para `color.neutral.0`) não acompanha a troca de modo; o validador avisa cada caso. Para categorias de dimensão (padding, altura de controle), crie semânticos de densidade (`density.control.padding-inline`) em vez de apontar o componente para a escala crua; se o projeto decidir permitir o salto em alguma categoria, isso é exceção registrada.
+
+Migrar um sistema achatado (`--button-primary-bg: #2563eb` direto) para três camadas: extraia os valores únicos para primitivos, dê a cada uso repetido um papel semântico, faça os componentes apontarem para os semânticos e só então crie os modos.
+
+## Convenção de nomes, uma só
+
+O caminho JSON é a identidade do token. O nome de saída é derivado dele por uma regra única, documentada e gerada, para que documentação e código nunca divirjam:
+
+- **Segmentos:** minúsculas ASCII em kebab-case. Primitivo: `{categoria}.{família}.{passo}` (`color.accent.600`, `radius.md`). Semântico: `{papel}.{variante}.{propriedade}` (`action.primary.bg`). Componente: `{componente}.{variante}.{propriedade}` (`button.primary.bg`).
+- **Estado é sufixo da propriedade**, nunca filho de um token: `action.primary.bg-hover`, `action.primary.bg-active`, `button.primary.fg-disabled`. Um token com `$value` não pode ter filhos.
+- **Nome CSS:** `--{prefixo}-{caminho sem o nome da camada, com pontos virando hífens}`. Com prefixo `ds`: `color.neutral.50` vira `--ds-color-neutral-50`; `surface.canvas` vira `--ds-surface-canvas`; `button.primary.bg` vira `--ds-button-primary-bg`. O prefixo é escolhido uma vez por projeto (curto, registrado no documento do sistema) e existe para não colidir com variáveis de bibliotecas, inclusive os namespaces do Tailwind (`--color-*`, `--radius-*`, `--spacing-*`).
+- **Unicidade:** o caminho sem camada precisa ser único entre as três camadas. Se um semântico colidir com um primitivo, renomeie o semântico.
+
+## Categorias
+
+Um sistema de produto cobre todas as categorias abaixo; um sistema de landing pode omitir as que não usa, dizendo que omitiu.
+
+- **Cor:** superfícies (canvas, elevada, afundada, inversa), texto (primário, secundário, desabilitado informativo, sobre ação, sobre status), bordas (`border.default` decorativa, forte, e `border.control` com 3:1), ação (primária, secundária, destrutiva, com hover e ativo opacos), foco, seleção (`::selection`, item selecionado), overlay (scrim de diálogo por modo), status (sucesso, aviso, erro, informação, cada um com fundo, primeiro plano e borda) e dados. Detalhe em [cor](cor.md).
+- **Cores de dados:** categórica (passos distinguíveis entre si e contra o fundo, validados em simulação de daltonismo, nunca o único canal de informação), sequencial (luminosidade monotônica), divergente (dois matizes com ponto médio neutro). Ver [dados e densidade](dados-e-densidade.md).
+- **Tipografia:** primitivos de família, tamanho, entrelinha, peso, tracking e recursos OpenType; semânticos compostos por papel (`display`, `headline`, `title`, `body`, `label`, `caption`, `code`; os cinco primeiros são os papéis do DESIGN.md comum, ver [documento do sistema](documento-do-sistema.md)), cada um com família, tamanho, entrelinha, peso, tracking e `font-feature-settings` (por exemplo `tnum` em `label` de dado). Ver [tipografia](tipografia.md).
+- **Espaço:** escala base 4 nos primitivos; semânticos de componente e de seção por densidade (tabela canônica de padding de seção abaixo).
+- **Raio:** escala nos primitivos; semânticos por tipo de forma (controle, contêiner, mídia) com a regra concêntrica: raio interno = raio externo − padding.
+- **Elevação:** escala de sombras tingidas nos primitivos; semânticos por nível (repouso, elevado, sobreposto) ou declaração de que o sistema usa borda em vez de sombra. Ver [superfície e profundidade](superficie-e-profundidade.md).
+- **Movimento:** primitivos nomeados por valor (duração) e por forma (curva); semânticos por propósito (`duration.instant/state/layout/focal`, `easing.enter/exit`, scrub e mola) e transições compostas por propriedade. Valores abaixo; uso em [movimento](movimento.md).
+- **Densidade:** altura de controle, padding de controle, altura de linha de tabela, padding de seção por faixa do botão DENSIDADE (tabela canônica abaixo), alvo mínimo em `pointer: coarse`.
+- **Breakpoints:** ditados pelo conteúdo, com container queries onde o componente é que muda; 640/768/1024/1280/1536px aparecem só como exemplo marcado.
+- **Camadas (z):** escala nomeada, nada arbitrário; a escala canônica está em [superfície e profundidade](superficie-e-profundidade.md).
+- **Foco:** largura do anel (2px), offset (2px), cor por modo com 3:1 contra os dois lados.
+- **Opacidade:** só para efeitos sem texto (scrim, sombra); estado desabilitado usa cores próprias, não opacidade sobre texto.
+
+**Borda de controle é papel próprio.** `border.control` é o limite de campo e de controle (input, select, checkbox, radio, botão contornado, card clicável): 3:1 ou mais contra a superfície adjacente em todos os modos, com os pares declarados em `$contrast`. `border.default` é divisória decorativa e não serve como único limite de nada interativo; o token de componente de um campo (`input.border`) aponta para `border.control`, nunca para `border.default`. Pares e números em [cor](cor.md).
+
+## Valores primitivos úteis, já corrigidos
+
+Referência para projetos sem escala própria; uma marca existente substitui qualquer um deles.
+
+**Espaço (base 4):** 0, 1px, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, 80, 96, 128, 160, 192px. Semânticos de partida: componente 4/8/12/16px (xs, sm, base, lg); seção pela tabela de densidade abaixo; margem lateral de página (page-x) 16px no celular; espaço vertical de página (page-y, entre o cromo e o primeiro bloco e antes do rodapé) 24px.
+
+**Padding vertical de seção por DENSIDADE (tabela canônica).** As outras referências ([layout e espaço](layout-e-espaco.md), [direção estética](direcao-estetica.md), [registro premium](registro-premium.md)) citam esta tabela em vez de repetir faixas próprias; mudar um número é mudar aqui.
+
+| DENSIDADE | Faixa | Padding vertical de seção (desktop) | Componente | Observação |
+|---|---|---|---|---|
+| 1–3 | arejada (galeria) | 128–192px (8–12rem) | folgado | Faixa do registro premium |
+| 4–7 | padrão | 64–96px (4–6rem) | padrão | Ainda admite cards quando a elevação comunica hierarquia |
+| 8–10 | cockpit | 24–48px (1.5–3rem) | justo | Sem cards genéricos, divisórias de 1px, números com `tabular-nums` |
+
+Qual faixa vale para cada tipo de superfície vem do botão DENSIDADE declarado no Design Read, com os sinais e presets de [direção estética](direcao-estetica.md) (painel e produto denso, por exemplo, ficam entre 6 e 8); esta tabela só converte o valor do botão em espaço. O registro premium usa a faixa arejada; uma tabela, um formulário ou uma lista de preços dentro dele mantêm a densidade que a tarefa exige. Os números são ponto de partida que a marca ajusta, sempre por token. No celular a faixa encolhe pelo token de densidade do breakpoint, nunca por valor solto na seção. Um único conjunto de tokens de densidade por superfície e nenhum padding mínimo fixo "para toda seção".
+
+**Tamanho de fonte:** 12, 14, 16, 18, 20, 24, 30, 36, 48px e display até 6rem (96px). Entrelinha: 1, 1.25, 1.375, 1.5, 1.625, 2. Pesos: 400, 500, 600, 700. Tracking: −0.04em (mínimo, só display latino), −0.025em, 0, 0.025em, 0.05em, 0.075em, 0.1em (de 0.05 a 0.1em só em caixa alta latina, ver [tipografia](tipografia.md)).
+
+**Raio:** 0, 2, 4, 6, 8, 12, 16, 24px e `radius.full` 9999px (pílula), o único nome para pílula em todo o pacote. Uma escala só por projeto, com regra de mistura documentada quando houver (por exemplo, botões em pílula, cards em 16px, campos em 8px).
+
+**Sombras (geometria com cor tingida):** a cor da sombra é um token derivado do matiz da superfície com luminosidade baixa (por exemplo `oklch(0.25 0.02 <matiz> / α)`), nunca preto puro em fundo claro; no escuro, a elevação vem mais de superfície mais clara que de sombra.
+
+| Nível | Geometria | Alfa |
+|---|---|---|
+| sm | `0 1px 2px 0` | .05 |
+| base | `0 1px 3px 0`, `0 1px 2px -1px` | .10 |
+| md | `0 4px 6px -1px`, `0 2px 4px -2px` | .10 |
+| lg | `0 10px 15px -3px`, `0 4px 6px -4px` | .10 |
+| xl | `0 20px 25px -5px`, `0 8px 10px -6px` | .10 |
+| 2xl | `0 25px 50px -12px` | .25 |
+| inner | `inset 0 2px 4px 0` | .05 |
+
+**Movimento: primitivos por valor, semânticos por propósito.**
+
+- **Durações primitivas, nomeadas pelo valor:** `duration.75`, `duration.100`, `duration.150`, `duration.200`, `duration.300`, `duration.500`, `duration.700`, `duration.1000` (ms).
+- **Curvas primitivas, nomeadas pela forma:** `easing.out-expo` `cubic-bezier(0.16, 1, 0.3, 1)`; `easing.standard` `cubic-bezier(0.2, 0, 0, 1)`; `easing.out-quart` `cubic-bezier(0.25, 1, 0.5, 1)`; `easing.in` `cubic-bezier(0.3, 0, 1, 1)`; `easing.none` `linear` (o `ease: none` das bibliotecas). A curva longa do registro premium (`cubic-bezier(0.32, 0.72, 0, 1)`) entra como primitivo próprio, nomeado pela forma, quando o registro a adota.
+- **Durações semânticas, por propósito:** `duration.instant` (feedback de pressão, toggle e hover, 100–150ms); `duration.state` (mudança de estado de rotina, 150–300ms; 150–250ms em Operar); `duration.layout` (layout, overlay, transição de view, 300–500ms; **em Operar, 250ms no máximo**, apontando para `duration.200`); `duration.focal` (entrada focal, 500–800ms, só em Persuadir e Experienciar; não existe em Operar).
+- **Easing semântico:** `easing.enter` aponta para `easing.out-expo` (ou `easing.standard` em UI de produto); `easing.exit` aponta para `easing.in` e a saída é mais curta que a entrada; scrub e progresso usam a curva nula; mola (rigidez e amortecimento) só onde há gesto ou interrupção. Os nomes semânticos completos, inclusive o de scrub e o de mola, estão em [movimento](movimento.md).
+- **Sob movimento reduzido,** os semânticos de deslocamento colapsam para 0 ou para crossfade curto; cor e opacidade continuam.
+
+**Mapa de transição por propriedade (transições de estado de controle: hover, foco, pressão, seleção).** São semânticos compostos que apontam para primitivos; layout, overlay e entrada focal usam `duration.layout` e `duration.focal`.
+
+| Propriedades | Token composto | Duração | Easing |
+|---|---|---|---|
+| `color`, `background-color`, `border-color`, `outline-color`, `text-decoration-color` | `transition.color` | 150ms (`duration.150`) | `easing.enter` ao entrar no estado, `easing.exit` ao sair |
+| `transform` | `transition.transform` | 200ms (`duration.200`) | idem |
+| `opacity` | `transition.opacity` | 150ms (`duration.150`) | idem |
+| `box-shadow` | `transition.shadow` | 200ms (`duration.200`) | idem |
+
+Corrigido da origem: lá a cor usava `ease-in-out`, a opacidade `ease` e o transform `ease-out`, sem distinguir chegada de saída; aqui o easing vem do propósito (uma troca simétrica de cor pode usar a mesma curva nos dois sentidos). A transição lista as propriedades (`transition-property` explícito, nunca `all`). Sob movimento reduzido, `transition.transform` colapsa para 0; as de cor e opacidade permanecem.
+
+**Camadas:** a escala canônica (ordem, nomes e valores espaçados) está em [superfície e profundidade](superficie-e-profundidade.md); aqui ela só vira tokens `z.*` com os mesmos nomes. Uma camada nova entra na escala, não no componente.
+
+**Densidade de tabela e controle:** linha compacta 40px, padrão 48px, confortável 56px; controle pequeno 32px, padrão 40px, grande 48px; em `pointer: coarse`, alvo efetivo de 44px.
+
+**Diálogo de partida (dado da origem, corrigido):** padding interno de 24px; sombra `lg` da escala acima, tingida; raio `lg` da escala do projeto (a própria origem diverge, 8px numa tabela e 12px noutra: escolha um e registre); largura máxima da ordem de 32rem; fundo, texto e borda pelos semânticos de superfície elevada; scrim pelo token de overlay do modo, não um preto a 50% fixo. Comportamento (foco, Esc, retorno de foco) em [componentes e estados](componentes-e-estados.md).
+
+**Paleta de referência comum e defaults de contraste corrigidos.** Muitos projetos já usam a paleta cinza/azul/verde/vermelho do Tailwind (cinza 50–950: `#F9FAFB #F3F4F6 #E5E7EB #D1D5DB #9CA3AF #6B7280 #4B5563 #374151 #1F2937 #111827 #030712`). Paleta nova na web nasce em OKLCH (ver [cor](cor.md)). Sobre essa paleta, os mapeamentos usuais reprovam em vários pares; os corrigidos (razões WCAG 2.x calculadas):
+
+| Papel | Comum e reprovado | Corrigido |
+|---|---|---|
+| ação primária, texto branco | blue-500 `#3B82F6`: 3.68 | blue-600 `#2563EB`: 5.17 (hover blue-700 `#1D4ED8`: 6.70) |
+| informação, texto branco | blue-500: 3.68 | blue-600: 5.17 |
+| sucesso, texto branco | green-600 `#16A34A`: 3.30 | green-700 `#15803D`: 5.02 |
+| destrutivo, texto branco | red-500 `#EF4444`: 3.76 | red-600 `#DC2626`: 4.83 |
+| texto atenuado sobre `#F3F4F6` | gray-500 `#6B7280`: 4.39 | gray-600 `#4B5563`: 6.87 |
+| borda de campo sobre branco | gray-200 `#E5E7EB`: 1.24 | gray-500 `#6B7280`: 4.83 (≥3:1) |
+| borda de campo no escuro, sobre `#030712` | gray-800 `#1F2937`: 1.37 | gray-500: 4.16 |
+| sucesso, texto branco (green-500 `#22C55E` da origem) | green-500: 2.28 | green-700 `#15803D`: 5.02; ou green-500 com texto gray-900: 7.79 |
+| aviso | yellow-500 `#EAB308` com texto gray-900 `#111827`: 9.25 (mantém) | — |
+| aviso, texto branco (yellow-600 `#CA8A04` da origem) | yellow-600: 2.94 | yellow-600 com texto gray-900: 6.04 (ou yellow-500 com gray-900: 9.25) |
+| informação declarada como `blue-500` no arquivo de primitivos (origem) | semântico na camada errada e 3.68 com branco | semântico `status.info` apontando para blue-600: 5.17 |
+
+**Rampa azul da origem, com contraste calculado** (razões WCAG 2.x; "reprova" = abaixo de 4.5 como texto normal):
+
+| Passo | Hex | Com texto branco | Com texto gray-900 `#111827` |
+|---|---|---|---|
+| 50 | `#EFF6FF` | 1.09 reprova | 16.30 |
+| 100 | `#DBEAFE` | 1.22 reprova | 14.54 |
+| 200 | `#BFDBFE` | 1.42 reprova | 12.48 |
+| 300 | `#93C5FD` | 1.80 reprova | 9.84 |
+| 400 | `#60A5FA` | 2.54 reprova | 6.98 |
+| 500 | `#3B82F6` | 3.68 reprova | 4.82 |
+| 600 | `#2563EB` | 5.17 | 3.43 reprova |
+| 700 | `#1D4ED8` | 6.70 | 2.65 reprova |
+| 800 | `#1E40AF` | 8.72 | 2.03 reprova |
+| 900 | `#1E3A8A` | 10.36 | 1.71 reprova |
+
+No escuro, sobre gray-950 `#030712`, blue-500 dá 5.47 e blue-400 dá 7.92 como texto ou ação. São dados da origem para quem já usa essa paleta, não recomendação de matiz.
+
+"Branco" aqui é o token de texto sobre ação; quando o sistema evita `#fff` puro, recalcule com o quase-branco escolhido. O modo escuro sobrescreve também ação, foco, status e destrutivo, não só fundo e texto: um primário que passa no claro não passa automaticamente no escuro.
+
+## Modos com paridade
+
+Os modos existentes (claro, escuro, alto contraste, ou só um) são decisão do contrato com o dono. Quando há mais de um:
+
+- Cada semântico que depende de luz tem valor em cada modo; o que um modo não sobrescreve herda o valor base, e essa herança precisa ser intencional.
+- Os pares de contraste são declarados uma vez e verificados em todos os modos.
+- Escuro não é inversão: superfícies elevadas ficam mais claras, croma cai, sombras pesam menos.
+- **Alto contraste** é modo de tokens próprio (bordas fortes, texto de contraste máximo, foco espesso), ativado por escolha explícita e por `prefers-contrast: more`. **`forced-colors: active`** é outra coisa: o navegador impõe as cores do sistema e os tokens de cor deixam de valer; a especificação garante borda e `outline` reais (nada que dependa só de `box-shadow` ou de fundo) e usa palavras-chave de cor de sistema (`Canvas`, `CanvasText`, `LinkText`, `ButtonText`, `Highlight`, `GrayText`) onde for preciso.
+- `color-scheme` acompanha o modo, para que controles nativos e barras de rolagem combinem.
+
+## Estado com alvo opaco
+
+Hover, ativo, selecionado e desabilitado têm tokens próprios com cor opaca (`action.primary.bg-hover`), nunca o mesmo token com alfa (`/90`, `/80`) ou "mais escuro" calculado no componente. Alfa muda o contraste conforme o fundo e não é verificável no par fg/bg; o validador recusa cor translúcida em par de contraste. Seleção em linha de tabela é um fundo opaco do modo, não o primário a 10%.
+
+## Saída: aliases, nunca literais resolvidos
+
+Toda saída preserva a referência entre camadas como alias. Na saída CSS, semânticos e componentes são `var()` de outra variável, nunca o valor resolvido; se o gerador gravar `--ds-button-primary-bg: #2563eb`, o modo escuro troca o semântico e o botão continua claro. Critério de aceite para quem implementa: trocar o modo e verificar que o valor computado de um token de componente mudou junto.
+
+### CSS custom properties
+
+Exemplo sintético a partir do template (prefixo `ds`, valores do template):
+
+```css
+:root {
+  color-scheme: light;
+  --ds-color-neutral-0: oklch(1 0 0);
+  --ds-color-neutral-50: oklch(0.98 0.004 240);
+  --ds-color-neutral-900: oklch(0.21 0.008 240);
+  --ds-color-neutral-950: oklch(0.15 0.006 240);
+  --ds-color-accent-300: oklch(0.82 0.085 195);
+  --ds-color-accent-700: oklch(0.42 0.058 195);
+
+  --ds-surface-canvas: var(--ds-color-neutral-50);
+  --ds-text-primary: var(--ds-color-neutral-900);
+  --ds-action-primary-bg: var(--ds-color-accent-700);
+  --ds-action-primary-fg: var(--ds-color-neutral-0);
+
+  --ds-button-primary-bg: var(--ds-action-primary-bg);
+  --ds-button-primary-fg: var(--ds-action-primary-fg);
+}
+
+[data-theme="dark"] {
+  color-scheme: dark;
+  --ds-surface-canvas: var(--ds-color-neutral-950);
+  --ds-text-primary: var(--ds-color-neutral-50);
+  --ds-action-primary-bg: var(--ds-color-accent-300);
+  --ds-action-primary-fg: var(--ds-color-neutral-950);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) { /* mesmas sobrescritas do bloco dark */ }
+}
+```
+
+O modo de alto contraste segue o mesmo desenho com `[data-theme="high-contrast"]` e `@media (prefers-contrast: more)`. O tema escolhido pelo usuário é aplicado antes da primeira pintura (script curto no `<head>` que lê a preferência salva), e a página escuta a mudança da preferência do sistema; sem isso, a página pisca no tema errado e ignora a troca do sistema operacional.
+
+### Tailwind v4
+
+Detecte a versão antes: `@import "tailwindcss"` com blocos `@theme` é v4; `tailwind.config.*` com `@tailwind base` é v3. Não misture sintaxes. Na v4, os tokens continuam nas custom properties com prefixo próprio, e o tema do Tailwind só mapeia nomes de utilitário para elas:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-*: initial; /* sem paleta crua: nada de bg-blue-600 fora do sistema */
+}
+
+@theme inline {
+  --color-canvas: var(--ds-surface-canvas);
+  --color-fg: var(--ds-text-primary);
+  --color-action: var(--ds-action-primary-bg);
+  --color-on-action: var(--ds-action-primary-fg);
+  --radius-control: var(--ds-radius-control);
+}
+```
+
+`@theme inline` faz o utilitário referenciar a variável, de modo que `bg-action` acompanha o modo sem variante `dark:`. Com tokens semânticos, `dark:` fica para exceções; escolha uma estratégia, não as duas. A sintaxe exata (`@theme inline`, o reset com `initial`, `@custom-variant`) é conferida na documentação da versão instalada por quem implementa.
+
+### Tailwind v3
+
+Mapeie em `theme.extend` com objetos aninhados e valores `var()`: `colors: { canvas: 'var(--ds-surface-canvas)', action: { DEFAULT: 'var(--ds-action-primary-bg)', hover: 'var(--ds-action-primary-bg-hover)' } }`. Chaves com ponto (`'primary.hover'`) não geram classe utilizável. Modificador de opacidade (`bg-action/50`) não funciona com `var()` de cor completa na v3, o que é mais um motivo para os tokens de estado opacos.
+
+### Exportação DTCG
+
+O template segue a estrutura do formato de tokens de design (DTCG): folhas com `$value` e `$type`, referência `{caminho.do.token}`, grupos aninhados. Para entregar a ferramentas que leem DTCG estrito (Style Dictionary, Tokens Studio e afins), exporte cada modo como um conjunto separado (a chave `modes` do template não é parte do formato; modos e temas no DTCG são conjuntos combinados por um resolvedor) e confira, na versão da especificação e da ferramenta de destino, se dimensão e duração precisam ser objeto de valor mais unidade, se cor precisa de espaço de cor e componentes, e se sombra, tipografia e transição são tipos compostos. O template usa strings por legibilidade; a conversão é da exportação, não do arquivo-fonte.
+
+## Governança
+
+- **Versão semântica do sistema** em `$meta.version`. MAJOR: remoção ou renomeação de token, mudança de significado de um semântico, remoção de modo. MINOR: token, modo ou variante novos, compatíveis. PATCH: ajuste de valor que mantém o significado e continua passando nos pares de contraste.
+- **Depreciação com alias e prazo:** o nome antigo continua existindo como referência ao novo (`{semantic.action.primary.bg}`), marcado com `"$deprecated"` e com `$description` dizendo o substituto e a versão de remoção. A marca é obrigatória: o validador só aceita semântico apontando para semântico quando ela existe, e avisa "use <alvo>". Se a ferramenta de destino não lê `$deprecated`, a exportação a converte; o arquivo-fonte a mantém. A remoção só acontece no próximo MAJOR.
+- **Changelog** por versão: adicionado, alterado, depreciado, removido, cada linha com motivo e, quando mexe em cor, a razão de contraste resultante. Vive no [documento do sistema](documento-do-sistema.md).
+- **Dono:** um papel nomeado (pessoa ou equipe) aprova mudanças. Fluxo: proposta (o que muda, por quê) → impacto (consumidores, modos, pares de contraste) → aprovação → incremento de versão → changelog.
+- **Exceções** com dono, motivo, escopo (qual token ou componente), validade (data ou versão) e plano de remoção, registradas no documento do sistema. Exceção sem validade vira regra escondida.
+- **Mapeamento design ↔ código:** tabela de token → variável CSS → utilitário, gerada da mesma fonte.
+- **Multimarca:** cada marca é um conjunto de sobrescritas semânticas sobre primitivos próprios ou compartilhados, validado como arquivo próprio ou como modos nomeados (`marca-a-claro`, `marca-a-escuro`), com a mesma paridade.
+- **Uma fonte de verdade:** o arquivo de tokens é normativo. Documento e saídas são gerados dele ou conferidos contra ele; nunca há duas fontes editadas à mão.
+
+## Validar
+
+Na pasta da skill (caminho relativo):
+
+```
+python3 scripts/validar_tokens.py <arquivo>
+python3 scripts/validar_tokens.py <arquivo> --json
+```
+
+Saída 0 sem erros, 1 com erros, 2 para erro de uso ou de estrutura (arquivo ausente, JSON inválido ou aninhado demais, camada obrigatória ausente, `defaultMode`, `modes`, `$contrast` ou `min` malformados). O script lê só o arquivo indicado, não acessa rede e não escreve nada. Rodado sobre o template, sai com 0 e imprime o resumo `0 erro(s), 0 aviso(s); N par(es) de contraste verificados em N modo(s)`.
+
+**O que ele checa:**
+- presença das camadas `primitive`, `semantic` e `component` e `$meta.version` em semver;
+- referências `{a.b.c}` que não resolvem, inclusive dentro de `$value` composto (objeto ou lista, como sombra, tipografia e transição), e ciclos de referência, na base e em cada modo;
+- direção das camadas, para cada referência de cada token e de cada sobrescrita de modo: primitivo não referencia nada; semântico só referencia primitivo; componente não referencia componente; componente apontando para primitivo gera aviso; valor literal em semântico ou componente gera aviso. Semântico apontando para semântico é erro, salvo quando o token antigo traz `"$deprecated"` (alias de depreciação): aí passa com o aviso "use <alvo>";
+- estrutura: nó com `$value` não pode ter filhos (erro, inclusive dentro de `modes`); segmento de nome com ponto é erro, porque colide com o caminho; JSON aninhado além de 100 níveis é estrutura inválida;
+- modos: sobrescritas em `modes` só podem apontar para semântico existente (os caminhos dentro de um modo são relativos a `semantic`);
+- contraste WCAG 2.x de cada par declarado em `$contrast` (`fg` e `bg` como caminhos de token sem chaves, `label` opcional), comparando a razão exata, sem arredondar (arredonda só na exibição), com o modo de `$meta.defaultMode` como base. `min` é número (padrão 4.5) ou objeto por modo, por exemplo `{"default": 4.5, "high-contrast": 7}`, em que `default` vale para os modos não listados; `modes` opcional no par restringe a verificação a esses modos; modo desconhecido é erro;
+- cores: hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`, `oklch()` (L em número ou %, C em número ou %, matiz em `deg`, `turn`, `rad`, `grad` ou `none`), `color(display-p3 …)` convertida para sRGB, e objeto DTCG (`colorSpace` `srgb` ou `oklch`, `components`, `alpha` opcional). Alfa abaixo de 1 num par e valores não finitos são rejeitados; fora do gamut sRGB gera aviso e a cor é recortada.
+
+Tokens do template úteis para conferir o formato: `semantic.border.control`, `semantic.duration.instant`, `semantic.duration.state`, `semantic.duration.layout`, `semantic.duration.focal`, `semantic.easing.enter`, `semantic.easing.exit`, e os primitivos `duration.100`, `duration.200`, `duration.300`, `duration.500`, `easing.out-expo`, `easing.standard` e `easing.in` (o template traz só esse subconjunto da escala acima).
+
+**O que ele não checa** (fica com você, no pré-voo):
+- o significado dos nomes, nem se um token nomeado por propósito está na camada certa: ele só confere a direção das referências, então um `semantic.color.blue` passa;
+- a convenção de nomes, a unicidade dos nomes CSS e o prefixo;
+- a completude das categorias e a paridade de modos (um semântico não sobrescrito herda o valor base em silêncio);
+- contraste de pares não declarados em `$contrast`: declare todos os pares reais (texto, texto secundário, texto sobre ação e status, `focus.ring` contra cada superfície que ele toca, `border.control` contra cada superfície, estados de hover e seleção);
+- `$type` contra `$value`, o formato de valores que não são cor e referências embutidas no meio de uma string maior;
+- gamut P3 como alvo (uma cor P3 é convertida e avaliada em sRGB), contraste APCA, `forced-colors` e o uso dos tokens no código (literal em componente, `var()` sem definição);
+- se o incremento de versão corresponde às mudanças e se aliases depreciados têm prazo.
+
+Tokens válidos são gate do contrato (ver [aceite e pré-voo](aceite-e-pre-voo.md)): o contrato não fecha com o validador saindo com 1 ou 2.

package/skills/crow-design/references/superficie-e-profundidade.md

@@ -0,0 +1,153 @@
+<!-- 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. -->
+# Superfície e profundidade
+
+Leia quando o contrato for decidir cards, bordas, sombras, raio, camadas (z-index), vidro, textura, fundo, ícones ou as superfícies do navegador (seleção, cursor, barra de rolagem).
+
+## Card é decisão de hierarquia
+
+Card só existe quando a elevação comunica hierarquia real: um objeto que se move, se seleciona, se arrasta ou precisa se distinguir do resto. Fora disso, a separação vem de espaço, de uma borda no topo entre blocos (`border-block-start`) ou de divisórias entre itens. Com densidade acima de 7, cards genéricos não entram: linhas de 1px e alinhamento fazem o trabalho. Card dentro de card não entra. Três cards iguais com ícone, título e texto como estrutura de página é o template mais reconhecível que existe.
+
+## Elevação: borda ou sombra, declarada uma vez
+
+O sistema escolhe **borda ou sombra** como linguagem de elevação e declara qual. Borda de 1px sob uma sombra larga e suave é o **card fantasma**: duas linguagens dizendo a mesma coisa, nenhuma decidindo.
+
+**Sombra** tem deslocamento vertical e desfoque suave, e é **tingida** pelo matiz da superfície em que cai (um escuro do próprio matiz com alfa baixo), nunca preto puro em fundo claro, que suja. Escala de referência, para trocar a cor pelo matiz do sistema:
+
+| Nível | Valor de referência |
+|---|---|
+| sm | `0 1px 2px 0` a 5% |
+| base | `0 1px 3px 0` a 10% + `0 1px 2px -1px` a 10% |
+| md | `0 4px 6px -1px` a 10% + `0 2px 4px -2px` a 10% |
+| lg | `0 10px 15px -3px` a 10% + `0 4px 6px -4px` a 10% |
+| xl | `0 20px 25px -5px` a 10% + `0 8px 10px -6px` a 10% |
+| 2xl | `0 25px 50px -12px` a 25% |
+| inner | `inset 0 2px 4px 0` a 5% |
+
+A cor é, por exemplo, `oklch(0.25 0.02 H / α)` com o H da superfície. Alfa em sombra é aceitável porque sombra não carrega texto; o limite de componente não pode depender dela.
+
+**Vícios de sombra:**
+
+- **Halo colorido sem deslocamento** (glow) é decoração, não profundidade, e quase sempre puxa para o cluster neon.
+- **Sombra dura deslocada sem desfoque** (`4px 4px 0`) só num mundo que é de fato neobrutalista, aplicada com coerência.
+- Sombra genérica de biblioteca (`shadow-md`) em tudo, ou preto a 30%, achata o sistema numa única elevação.
+
+**No escuro,** a elevação sobe pela luminosidade da superfície (mais alto, um pouco mais claro), não por sombras mais fortes, que quase não se veem. No Android, isso é a elevação tonal do Material.
+
+## Limite de componente interativo
+
+Quando a borda é o único limite de um controle interativo (input, select, checkbox, botão contornado, card clicável), ela precisa de **3:1** contra o fundo adjacente, em cada modo. Hairlines com alfa muito baixo (preto a 5% sobre branco dá 1.12:1; branco a 10% sobre quase-preto, 1.22:1) servem só em superfície decorativa e não interativa. Card puramente decorativo não exige 3:1, mas, se a separação some (card branco sobre canvas quase branco dá 1.05:1), escolha tint, sombra calculada ou borda real em vez de uma borda invisível. Pares e números em [cor](cor.md).
+
+## Raio como sistema
+
+O raio é uma escala com regra de mistura, não um valor aplicado a tudo, e não há valor imposto pela ferramenta: cada mundo escolhe o seu.
+
+**Trava de forma.** O sistema declara uma das opções: tudo reto (0), tudo médio (12 a 16px), ou pílula nos interativos com o resto em outra regra. Mistura só com regra escrita, por exemplo "botões em pílula, cards 16px, inputs 8px". Raio decidido componente a componente é ruído.
+
+- **Escala de referência:** 0, 2, 4, 6, 8, 12, 16, 24px e pílula pelo token `radius.full` (9999px); toda receita em pílula deste pacote usa esse token, não um número solto.
+- **Card de 12 a 16px** é um default sugerido para mundos neutros, não regra: um mundo técnico pode ser reto, um mundo infantil pode ser muito redondo.
+- **Pílula** fica para controles pequenos (botão, chip, badge, toggle), não para cards e contêineres grandes, salvo regra declarada.
+- **Raio concêntrico:** elemento dentro de outro com padding usa raio interno igual ao externo menos o padding (externo 2rem com padding de 0.375rem dá interno `calc(2rem - 0.375rem)`). Mesmo raio dentro e fora parece desalinhado.
+
+## Camadas (z-index)
+
+A escala é token, documentada num lugar só; nenhum componente inventa `z-index: 50` ou `9999`. Ordem de referência, de baixo para cima: base, elevado, sticky (nav e cabeçalhos fixos), dropdown, overlay (scrim), modal, popover e tooltip, toast, grão (textura decorativa, sempre com `pointer-events: none`). Valores espaçados (0, 100, 200 e assim por diante) permitem inserir uma camada sem renumerar. `<dialog>` modal e a API de popover vão para a camada superior do navegador e dispensam a escala; o contrato diz o que convive com eles. A camada de cada overlay e a árvore de decisão entre inline, disclosure, popover e modal estão em [layout e espaço](layout-e-espaco.md).
+
+## Vidro e translucidez
+
+Vidro é efeito com lugar certo, não decoração geral:
+
+- **Onde:** só em camada fixa ou sobreposta (nav, overlay, controle sobre mídia, menu em tela cheia). Nunca em card de conteúdo que rola nem em área grande: `backdrop-filter` em área que rola custa caro em celular e borra a leitura.
+- **Quando:** briefs que pedem (premium consumer, adjacência à Apple, luxo, overlay de mídia). Nunca em dashboard, setor público ou B2B sóbrio.
+- **Receita de referência:** fundo da superfície com alfa (da ordem de 60 a 80% sobre mídia; mais opaco quando há texto pequeno), `backdrop-filter: blur(24px)` a `blur(40px)` (64px no menu de tela cheia, que também escurece ou clareia o fundo a cerca de 80%), contorno de 1px em branco a 10%, brilho interno `inset 0 1px 0` em branco a 10%.
+
+Fallbacks obrigatórios, **por modo**:
+
+```css
+/* H = matiz da superfície do sistema; valores ilustrativos de formato */
+.vidro { /* claro */
+  background: oklch(0.98 0.004 H / 0.72);
+  backdrop-filter: blur(24px) saturate(160%);
+  border: 1px solid rgb(255 255 255 / 0.1);
+  box-shadow: inset 0 1px 0 rgb(255 255 255 / 0.1);
+}
+@media (prefers-color-scheme: dark) {
+  .vidro { background: oklch(0.2 0.01 H / 0.64); }
+}
+@supports not (backdrop-filter: blur(1px)) {
+  .vidro { background: oklch(0.98 0.004 H); }
+  @media (prefers-color-scheme: dark) { .vidro { background: oklch(0.2 0.01 H); } }
+}
+@media (prefers-reduced-transparency: reduce) {
+  .vidro { background: oklch(0.98 0.004 H); backdrop-filter: none; }
+}
+@media (prefers-reduced-transparency: reduce) and (prefers-color-scheme: dark) {
+  .vidro { background: oklch(0.2 0.01 H); }
+}
+@media (forced-colors: active) {
+  .vidro { border: 1px solid CanvasText; }
+}
+```
+
+O fallback de transparência reduzida usa a superfície opaca **do próprio modo**. Forçar uma superfície clara também no escuro (o erro da receita de origem) deixa texto claro sobre fundo quase branco justamente para quem pediu acessibilidade. O contraste é verificado nos quatro cenários: claro, escuro, e cada um com transparência reduzida; e sem nenhum desfoque, porque o texto precisa passar mesmo sobre a pior parte da mídia por trás. Quando o tema é trocado por classe ou atributo, os mesmos blocos se repetem com o seletor do tema.
+
+### Aproximação de Liquid Glass
+
+Não existe folha CSS oficial de Liquid Glass para a web: o material pertence às APIs das plataformas Apple. Quando o brief pede o efeito na web, ele é uma **aproximação rotulada como tal** no contrato e no código. Valores de referência:
+
+- **Base (claro):** `border-radius: var(--ds-radius-full)` (token `radius.full`); `position: relative; isolation: isolate; overflow: hidden`; `border: 1px solid rgb(255 255 255 / .32)`; fundo `linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)), rgb(255 255 255 / .12)`; `backdrop-filter: blur(24px) saturate(180%) contrast(1.05)` (com o prefixo `-webkit-`); sombras `inset 0 1px 0 rgb(255 255 255 / .48)`, `inset 0 -1px 0 rgb(255 255 255 / .12)` e uma sombra ampla `0 18px 60px oklch(0.25 0.02 H / .18)`, **tingida pelo matiz H da superfície** sobre a qual o vidro flutua, nunca `rgb(0 0 0 / …)` em fundo claro (a origem usava preto puro, que suja).
+- **`::before`** (brilho, `z-index: -1`, `pointer-events: none`): `radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%)` mais `linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14))`.
+- **`::after`** (contorno interno): `inset: 1px`, `border: 1px solid rgb(255 255 255 / .14)`, raio herdado.
+- **Escuro:** borda branca a .18; fundo `linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04))` sobre `rgb(15 23 42 / .42)`; sombras `inset 0 1px 0 rgb(255 255 255 / .22)` e a ampla `0 18px 60px oklch(0.12 0.02 H / .42)`, também tingida pelo matiz da superfície. O valor `rgb(15 23 42)` é o dado da origem: o tom do fundo escuro deriva do matiz da superfície do sistema e não deve cair no cluster da ardósia azul-preta.
+- **Transparência reduzida:** superfície **opaca de verdade** (alfa 1) do próprio modo: o semântico de superfície elevada clara no claro e o escuro no escuro, sem desfoque e sem os gradientes translúcidos. Branco a .96 não é opaco e não serve (a origem o usava).
+- **`forced-colors`:** borda real com `CanvasText`.
+
+O suporte de `prefers-reduced-transparency` e de `backdrop-filter` com vários filtros é desigual entre navegadores; o contraste precisa passar mesmo sem desfoque. Esta é a receita canônica de vidro e de Liquid Glass do pacote; [direção estética](direcao-estetica.md) e [registro premium](registro-premium.md) linkam aqui em vez de repetir valores.
+
+## Moldura dupla (Double-Bezel)
+
+Técnica opcional para mídia de destaque e hero, nunca em input (duas bordas confundem o limite do campo) e nunca em todo card:
+
+- **Casca externa:** fundo com alfa muito baixo (preto a 5% no claro, branco a 5% no escuro), contorno de 1px (preto a 5% ou branco a 10%), padding de 6 a 8px, raio de 2rem.
+- **Núcleo:** fundo próprio, brilho interno `inset 0 1px 1px rgb(255 255 255 / .15)`, raio concêntrico `calc(2rem - 0.375rem)`.
+
+A hairline da casca é decorativa; se o elemento é interativo, o limite real precisa de 3:1. Uso no registro premium em [registro premium](registro-premium.md).
+
+## Fundo, textura e imagem
+
+Fundo é superfície, e a textura vem do mundo do assunto.
+
+- **Grão e ruído:** textura estática numa camada fixa de tela inteira (`position: fixed; inset: 0; pointer-events: none`), na posição de grão da escala de camadas, com opacidade muito baixa (da ordem de 3%). Nunca num contêiner que rola (repinta a cada quadro) e nunca animado. Use uma textura pré-renderizada leve em mosaico. Grão decorativo gerado ao vivo por filtro de turbulência (`feTurbulence`) lê como amador e custa caro; distorção **funcional** com filtro SVG (deslocamento, máscara que serve à ideia) é permitida com orçamento de desempenho declarado.
+- **Listras e grades:** `repeating-linear-gradient` e grades sobrepostas em dois eixos só quando existe de fato um canvas, mapa, planta ou instrumento de medida por baixo. Linhas de grade ou miras como enfeite não entram.
+- **Fisicalidade falsa:** bisel, relevo, metal estampado, giz ou couro feitos em CSS imitando material leem como imitação. Se o mundo pede material, use asset real (foto, render) ou abstraia.
+- **Máscaras geométricas no lugar de recorte orgânico:** círculo, polígono ou recorte radial imitando o contorno de um sujeito fotográfico é a versão barata. Use matte com alfa derivado da imagem ou recorte real. `clip-path` com muitos vértices onde deveria haver um asset é o mesmo erro.
+- **Raster enterrado:** imagem com opacidade quase zero ou atrás de um véu que a apaga não é decisão de imagem; ou ela aparece, ou sai.
+- **Ilustração é real ou não existe:** cena SVG em estilo esboço não substitui ilustração. SVG fazendo geometria (formas exatas, diagramas, desenho de linha) é legítimo. SVG inline acima de algo como 64px ou com mais que alguns paths está fazendo papel de ilustração e pede asset próprio.
+- **Hero precisa de visual real:** texto sobre uma bolha de gradiente não é hero. Interface de produto falsa montada com `<div>` não substitui screenshot real, componente real ou foto. Origem, licença e rótulo de asset em [texto e conteúdo](texto-e-conteudo.md).
+
+## Ícones
+
+- **Uma biblioteca por projeto**, com **uma espessura** de traço global que acompanha o peso do texto ao lado (por exemplo 1.5 com texto regular, 2 com texto semibold). Traço ultrafino em tamanho pequeno perde legibilidade e contraste.
+- **Contraste não-texto de 3:1** para ícones que informam (status, ação sem rótulo). Ícone ao lado de rótulo é decorativo e sai da árvore de acessibilidade; ícone sozinho precisa de nome acessível.
+- **Tamanho:** 16 a 24px em interface, alinhados à altura de versal do texto e não à caixa.
+- **SVG autoral** só quando é uma marca geométrica simples ou um ícone que a biblioteca não tem, desenhado na mesma grade e espessura.
+- **Emoji e caracteres Unicode** (setas, estrelas, marcadores) não são sistema de ícones: renderizam diferente em cada plataforma e não seguem cor, peso nem tamanho. Emoji só em conteúdo de voz deliberadamente informal, com parcimônia.
+- **Bibliotecas citadas como opções** (nenhuma é obrigatória e todas têm o nome a conferir no registro de pacotes na hora da implementação): Phosphor (`@phosphor-icons/react`), Hugeicons (o pacote para React mudou de nome entre versões), Radix Icons (`@radix-ui/react-icons`), Tabler (`@tabler/icons-react`), Lucide (`lucide-react`), Remix Icon. Se o projeto já tem uma, ela vence.
+- Ícones direcionais espelham em RTL. Navegação só com ícones, sem rótulo, falha para quem não reconhece o símbolo.
+
+## Superfícies do navegador
+
+As partes que ninguém desenhou também carregam o design; o contrato as tematiza a partir da paleta:
+
+- **Seleção de texto** (`::selection`) com par de cor que mantém 4.5:1.
+- **Cursor de inserção** (`caret-color`) na cor de ação.
+- **Barra de rolagem:** muda-se a cor (`scrollbar-color`, `scrollbar-width`), nunca o comportamento. Barra customizada que some, encolhe a área de toque ou rola diferente é reinvenção de affordance; em Operar, a affordance nativa é preservada.
+- **Sublinhado de link** com `text-underline-offset` e espessura decididos, sem remover o sublinhado no meio de texto.
+- **Numerais tabulares em dado** (`font-variant-numeric: tabular-nums`) em tabela, métrica e coluna que se compara; regras em [dados e densidade](dados-e-densidade.md).
+- **Controles nativos** (checkbox, radio, range) com `accent-color` antes de qualquer reimplementação.
+- **`color-scheme`** declarado para que formulários e barras nativas acompanhem o modo.
+- **Anel de foco** com `outline` real (ou `box-shadow` mais `outline: 2px solid transparent`) para sobreviver a `forced-colors`; especificação em [componentes e estados](componentes-e-estados.md).
+- **Cursor customizado** é default recusável (ver [anti-padrões](anti-padroes.md)): só em Experienciar, quando o cursor é parte da obra, com o cursor do sistema preservado sobre controles e texto e sem atraso de seguimento sob movimento reduzido. Fora disso, atrapalha quem depende do cursor do sistema (tamanho, contraste) e não traz informação.
+
+## `forced-colors`
+
+Em `forced-colors: active`, sombras, gradientes e fundos translúcidos somem. Todo limite de componente, estado selecionado e indicador de foco que dependia deles ganha `border` ou `outline` reais. Ícones SVG usam `currentColor`. Não tente reimpor a paleta da marca nesse modo: o sistema decide as cores.

package/skills/crow-design/references/texto-e-conteudo.md

@@ -0,0 +1,149 @@
+<!-- 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. -->
+# Texto e conteúdo
+
+Leia quando o contrato for especificar o vocabulário da interface, mensagens de estado, formulários, pontuação, tradução, conteúdo de exemplo, imagens, logos, depoimentos ou qualquer asset que vai para a entrega.
+
+## Texto é conteúdo de projeto
+
+O contrato especifica o vocabulário com o mesmo cuidado que especifica espaçamento. Texto que fica para depois é escrito na pressa da implementação, uma tela de cada jeito.
+
+- **Nome pelo que a pessoa entende, não pela implementação.** Alguém gerencia notificações, não configura webhooks; arquiva uma conversa, não muda o status para 3.
+- **Uma ação, um nome, do começo ao fim.** O botão "Publicar" produz a confirmação "Publicado" e o filtro "Publicados"; não "Postar" num lugar, "Enviar" no outro e "Ativo" no terceiro. A mesma palavra para o mesmo conceito em toda a superfície; em interface, variar o termo por elegância literária é defeito.
+- **Verbo mais objeto, descrevendo o resultado,** quando o resultado não é óbvio: "Salvar alterações", "Enviar convite", "Exportar CSV". O rótulo diz o que vai acontecer, não o gesto ("Clique aqui").
+- **Destrutiva nomeia o objeto e a consequência:** "Excluir projeto e as 14 tarefas dele". Quando a recuperação é segura, **desfazer vem antes de confirmação**: excluir na hora e oferecer "Desfazer" é mais rápido e mais honesto do que perguntar "Tem certeza?". Quando a confirmação é necessária, a pergunta e o botão repetem a ação ("Excluir projeto?" / "Excluir projeto").
+- **Nada de Sim, Não, OK, Enviar genéricos.** Eles obrigam a ler a pergunta de novo para saber o que cada um faz.
+- **Voz ativa, caixa de frase, a língua do produto.** Caixa alta só em sigla. Um registro de texto por página: nada de manifesto num bloco e manual técnico no seguinte.
+- **Cada ideia é dita uma vez.** Se o título já explica o estado, a introdução traz informação nova ou some.
+
+A voz é constante; o tom se adapta ao momento (mais seco num erro de pagamento, mais leve num primeiro uso). Linguagem simples sem achatar o termo técnico que o público de fato conhece. Um glossário curto fixa os termos quando a inconsistência atravessa o produto.
+
+## Hierarquia da mensagem
+
+Para cada estado, o contrato decide, nesta ordem:
+
+1. **O fato agora:** a única coisa que a pessoa precisa saber.
+2. **A próxima ação:** o que ela pode fazer.
+3. **O contexto que muda a decisão:** só o que altera a escolha (prazo, custo, o que se perde).
+4. **O tom** adequado ao momento.
+
+## Mensagens por tipo
+
+**Erro.** Responde três perguntas: o que falhou; por quê, quando se sabe e ajuda; como recuperar ou que alternativa resta. Exemplo: "Não foi possível enviar a fatura. O e-mail do cliente está vazio. Adicione um e-mail e envie de novo." Sem código interno como mensagem principal (o código pode ir num detalhe para o suporte). Sem culpar a pessoa ("Você digitou errado"). Sem prometer causa ou solução que o sistema não conhece ("O servidor está em manutenção" quando só houve timeout). Privacidade, pagamento, exclusão, perda de acesso e trabalho bloqueado são tratados com seriedade: calor humano é bem-vindo, piada não. Erro perto da causa, sem apagar o que foi digitado.
+
+**Carregando.** Nomeia a operação real ("Gerando relatório de outubro") e cria expectativa honesta quando a espera é significativa ("Costuma levar menos de um minuto" só se for verdade). Progresso determinado quando existe; nunca progresso inventado, nunca barra que anda sozinha até 90% e para.
+
+**Vazio.** Diferencia os seis tipos canônicos (primeiro uso; limpo pelo usuário; sem resultado de busca; filtro sem resultado; sem permissão; falha ao carregar), e cada um explica o estado e oferece a próxima ação útil (lista e formas completas em [componentes e estados](componentes-e-estados.md#estado-vazio)). "Nenhum resultado" sozinho é beco sem saída: diga qual consulta, sugira ajuste, ofereça limpar.
+
+**Sucesso.** Confirma o resultado concluído, curto: "Convite enviado." Menciona a próxima consequência só quando muda o que a pessoa deve fazer ("Convite enviado. Ele expira em 7 dias."). Sucesso rotineiro não grita nem comemora.
+
+**Permissão.** Diz que o recurso existe, por que não está acessível e quem concede: "Este relatório é restrito à equipe financeira. Peça acesso a quem administra a conta."
+
+**Ajuda e instrução.** O texto de ajuda responde a pergunta implícita em vez de repetir o controle ("Usamos o telefone só para recuperar a conta", não "Digite seu telefone"). Detalhe incomum fica atrás de revelação progressiva. Texto de link faz sentido fora de contexto ("Ver política de reembolso", não "Clique aqui" nem "Saiba mais" repetido cinco vezes). Controle só com ícone tem nome acessível.
+
+## Formulários
+
+- Rótulo persistente; placeholder é exemplo do formato, não rótulo.
+- Requisitos de formato e elegibilidade antes do envio, junto do campo.
+- Dizer por que a informação é pedida só quando não é óbvio.
+- Obrigatório e opcional com tratamento consistente.
+- Validação diz o que precisa de atenção e como corrigir, sem culpar, perto do campo, anunciada de forma acessível (mecânica em [componentes e estados](componentes-e-estados.md)).
+
+## Como auditar o texto que o contrato propõe
+
+Leia o fluxo inteiro, não strings soltas, e passe por oito perguntas: há ambiguidade (substantivo, verbo, ação)? jargão ou conhecimento suposto? rótulo, resultado ou estado vago? falta a consequência, a recuperação ou o prazo? a terminologia ou a caixa é inconsistente? há redundância (título, introdução, ajuda e confirmação dizendo o mesmo)? o texto quebra em largura realista ou traduzido? o tom ignora estresse, risco, sucesso ou urgência?
+
+Depois, para copy **gerada**, uma releitura de cada string: reescreva o que estiver gramaticalmente quebrado, com referente obscuro, com cara de alucinação ou de texto tentando soar profundo. O texto final é o mais curto possível sem perder sentido nem recuperação; cortar não é meta, é consequência.
+
+Verificação do texto no contrato: compreensível sem conhecimento escondido do produto; acionável em erros, vazios e pontos de decisão; factualmente correto; consistente; varrível nas larguras alvo e com zoom de 200%; resistente a nome longo, expansão de tradução, plural e valor dinâmico; nomes acessíveis e anúncios de estado definidos; tom proporcional à consequência.
+
+## Texto fornecido e claims
+
+A heurística anti-clichê e a releitura valem para copy que você está gerando. **Texto fornecido pelo dono ou pelo cliente não é reescrito**: ele entra como veio, e qualquer sugestão vai separada, como proposta. Pergunte antes de mudar uma alegação factual, um sentido jurídico, um termo que pode ser de domínio ou um número. Quando há uma composição aprovada com texto, as palavras dela entram literalmente; reescrever é decisão declarada. Textos legais, de consentimento e de cookies não mudam sem aprovação.
+
+## Pontuação por locale
+
+A pontuação segue as convenções do idioma do produto, e o contrato escreve os caracteres reais, não os aproximados do teclado:
+
+- **Português do Brasil:** o travessão (—) é legítimo em diálogo, aposto e inciso; o meia-risca (–) é o caractere certo para intervalos ("2018–2026", "R$ 40–80 mil", "segunda–sexta"); aspas curvas “ ” e, dentro delas, ‘ ’; reticências como caractere (…) em estados de carregamento.
+- **Inglês:** as mesmas aspas curvas “ ” ‘ ’, meia-risca em intervalos, travessão conforme o guia de estilo adotado.
+- **Francês e outros locales que usam guillemets:** « » com o espaço que a norma local pede.
+- Aspas retas (" ') não são aspas tipográficas; exemplo de aspas tipográficas escrito com aspas retas ensina o erro.
+
+Há um vício de texto gerado, sobretudo em inglês, que usa travessão como muleta para emendar frases. A heurística contra ele vale **só para copy gerada** e consiste em preferir pontuação mais simples quando o travessão não está fazendo trabalho gramatical. Ela nunca reescreve texto fornecido, nunca proíbe o caractere, nunca troca o meia-risca de um intervalo por hífen e nunca se sobrepõe ao locale. O ponto médio (·) como separador de metadados é usado com parcimônia: no máximo um por linha.
+
+## i18n das strings
+
+- Mensagens inteiras traduzíveis; nada de concatenar fragmentos ("Você tem " + n + " novas " + "mensagens") que impedem a tradução de reordenar a frase.
+- Variáveis e números estruturados com nome, para que o tradutor possa movê-los ("{count} faturas vencem em {date}").
+- Plural pelas regras do idioma (há idiomas com mais de duas formas), não por "s" condicional.
+- Espaço para expansão de 30 a 40% em vez de abreviar cedo; nenhum contêiner de texto com largura fixa.
+- Datas, horas, números e moedas formatados pelo locale.
+- Glossário de termos por idioma, para que "projeto" não vire três palavras diferentes na tradução.
+- Nada de texto embutido em imagem.
+
+## Limites por medida visual
+
+Limites de tamanho de texto são definidos pela composição, em linhas e largura, e testados com a tradução mais longa; contagem de palavras em inglês não serve para português, alemão ou qualquer outro idioma. Como heurísticas de composição, com motivo e escape:
+
+- **Título do hero:** até duas linhas no desktop. Quatro linhas costumam ser erro de tamanho de fonte, não de texto. Cede quando o mundo da direção é tipográfico e o título é a própria peça.
+- **Subtítulo do hero:** até três ou quatro linhas na largura de leitura.
+- **Título de seção:** uma ou duas linhas; subtítulo curto o suficiente para ser lido de relance.
+- **CTA:** uma linha no desktop, sem `max-width` que force quebra.
+- **Citação:** até três linhas na composição.
+- **Texto corrido:** medida de 45–75ch, alvo 60–70ch.
+
+Quando o texto real ou traduzido não cabe, o contrato muda a composição ou o tamanho; não corta o texto em silêncio.
+
+## Clichês gerados a evitar
+
+Valem para copy gerada. Se o dono ou a marca usam uma dessas palavras de propósito, ela fica.
+
+- **Verbos e adjetivos de enchimento:** "elevar", "potencializar", "alavancar", "sem atrito", "sem complicação", "desbloquear", "liberar o potencial", "revolucionar", "próxima geração", "de ponta", "transformar a forma como você…", "tudo em um só lugar", "feito para você"; em inglês, *elevate*, *seamless*, *unleash*, *unlock*, *next-gen*, *revolutionize*, *supercharge*, *empower*, *effortless*, *cutting-edge*, *game-changer*.
+- **Prova social ensaiada:** "silenciosamente usado por", "a escolha discreta de", *quietly in use at*, *quietly trusted by*, *trusted by teams at* sem relação comprovada.
+- **Rótulos poéticos acima do conteúdo:** "Do campo", "Notas de campo", "Na bancada agora", "Na nossa mesa", "Pranchas soltas"; *From the field*, *Field notes*, *Currently on the bench*, *On our desks*, *Loose plates*.
+- **Humildade encenada:** referências fingidamente modestas ("Respeitamos os franceses", *We respect the French ones*).
+- **Micro-frase meta** sob um rótulo, explicando a seção em vez de ser a seção ("Cada um destes é um recurso que entregamos hoje…").
+- **Rótulo de etapa genérico:** "Etapa 1", "Passo 01", "Fase um", *Stage 1*, *Step 1*, *Phase 01*, *Pass One*; use o verbo da etapa ("Conecte sua conta").
+- **Faixa decorativa de palavras** no pé do hero ("MARCA. MOVIMENTO. ESPAÇO.", "DESENHAR · CONSTRUIR · ENTREGAR").
+- **Cromo de metadado:** rótulo de versão no hero ("v2.0", "BETA", "ACESSO ANTECIPADO") fora de um lançamento real; rodapé de versão ou build em página de marketing; contador de estoque decorativo ("Reserva 412 de 800"); faixa de cidade, hora e clima ("LIS 14:23 · 18°C") salvo estúdio distribuído, marca de viagem ou local físico real; sub-rótulo "Marca · Nº 01"; intervalo de anos como rótulo ("Índice de trabalhos, 2018–2026"); chamada para rolar ("Role para explorar", seta, ícone de mouse); "PALAVRA — fragmento" como padrão de rótulo.
+- **CTAs de mesma intenção duplicados** na mesma página: "Fale conosco", "Entre em contato", "Vamos conversar", "Comece um projeto", *Get in touch*, *Contact us*, *Let's talk*, *Reach out* são todos contato; "Teste grátis", "Começar", "Cadastre-se grátis", *Try free*, *Get started*, *Sign up free* são todos cadastro; "Ver trabalhos", "Ver projetos selecionados", *View work*, *Browse projects* são todos portfólio. Um rótulo por intenção.
+- **Nomes de template:** empresas Acme, Nexus, SmartFlow, Cloudly e afins; pessoas "Fulano de Tal", "João Silva", *Jane Doe*, *John Smith*.
+
+## Honestidade de conteúdo e assets
+
+**Conteúdo real primeiro.** O contrato usa o conteúdo real que existe. Quando falta, o conteúdo de exemplo é rascunho plausível **rotulado como ilustrativo**: no protótipo, por um atributo ou componente de placeholder visível (não só um comentário no código), e no contrato, numa **lista de substituição** entregue ao dono, com onde está cada mock e o que precisa entrar no lugar. A lista é **bloqueante**: nada é publicado enquanto ela tiver itens abertos.
+
+**Proibido, sob qualquer brief:**
+- Depoimento, pessoa, cargo, cliente, avatar ou logo de terceiro inventados com cara de reais.
+- Métrica, percentual, preço, contagem de clientes, benchmark, prêmio ou data inventados com aparência de medidos. Precisão falsa ("47,2%", "4,1×", "48 mil", "13,4 kg") é aceitável só quando vem de dado real ou está visivelmente rotulada como exemplo; "dado orgânico e bagunçado" inventado para parecer real é a mesma falsificação, mais convincente.
+- Screenshot de produto falso montado com divs, rodapé de versão inventado dentro dele ("v0.6.2-rc.1"), "última sincronização há 4s". Use captura real, preview com o componente real ou foto editorial rotulada.
+- Telefone, e-mail ou endereço que podem pertencer a alguém. E-mail em domínio reservado e marcado como exemplo: `nome@example.com` (também `example.org`, `example.net`) ou o TLD `.test` (`contato@exemplo.test`). Telefone: o Brasil **não tem faixa reservada para ficção** (prefixos de aparência fictícia costumam ser válidos e discáveis), então use placeholder não discável e rotulado, como `(00) 0000-0000` com a etiqueta "exemplo"; a faixa 555-0100 a 555-0199 só vale para números dos EUA.
+- Nome de exemplo com aparência de pessoa real sem rótulo. Quando o mock precisa de nome, use um plausível para o locale e rotule.
+
+**Logos de terceiros** só com relação comprovada (cliente, parceiro, integração real), seguindo as diretrizes de uso de cada marca. Quando a relação existe, a parede de logos mostra só os logos, sem rótulo de categoria embaixo (o nome vai no `alt`), legíveis nos dois modos, abaixo do hero e não dentro dele. Fontes de SVG de marca: Simple Icons e devicon, usados só com relação comprovada, apenas o logo (sem compor com outros elementos), com `alt` e legível nos dois modos; as diretrizes da própria marca prevalecem sobre a versão do repositório. Para marca inventada em protótipo, um monograma simples rotulado como provisório. O logo do próprio produto vem do dono.
+
+**Imagens:**
+- Prioridade: asset real do dono ou cliente; depois asset licenciado com origem registrada; depois placeholder rotulado nas dimensões certas.
+- **Placeholder** (serviço de imagem aleatória como o picsum, retângulo cinza com dimensões) nunca é entregável final; leva rótulo visível e entra na lista de substituição com tamanho e assunto ("foto de produto em uso, 1600×1200").
+- **Imagem gerada** só com consentimento do dono, para mood, textura ou ilustração, rotulada como gerada, com prompt ou origem registrados, e **nunca representando o produto real**, pessoa real ou resultado prometido.
+- **Referência colhida em busca, pin ou feed** serve para conversar sobre direção e não entra no entregável.
+- **Fotos de pessoas** de banco de imagens têm restrições de licença comuns: pessoa identificável não pode aparecer endossando produto, nem em contexto sensível (saúde, finanças, política) sem autorização de modelo; marcas visíveis na foto têm direitos próprios. "Grátis para usar" não quer dizer "grátis para qualquer uso".
+- **Proveniência por asset:** todo asset que entra (imagem, ícone, ilustração, fonte, vídeo, som) tem origem, licença, uso permitido e, quando gerado, o prompt registrados no contrato. Fonte: a da marca primeiro; depois livre (OFL, Fontshare) ou comercial com licença declarada e um fallback livre equivalente; nunca supor que uma fonte comercial "está disponível".
+
+**Página só de texto.** Quando o assunto pede imagem, texto puro não é minimalismo e um hero de texto com mancha de gradiente não é hero: duas ou três imagens reais (hero, produto ou uso, apoio) costumam bastar. Quando o modo é Ler e a direção é tipográfica, texto puro é decisão legítima. SVG decorativo desenhado à mão é desencorajado; entra quando pedido, quando é marca geométrica simples ou geometria exata (diagrama, forma, linha animada).
+
+**Emoji** não entra em interface, markup ou texto por padrão; uma voz lúdica, social ou de chat pode liberar com parcimônia, nunca como ícone e nunca no `alt`.
+
+**Depoimentos e citações** só reais e autorizados, com nome, cargo e, quando houver, empresa, em aspas tipográficas do locale, até três linhas na composição.
+
+## Alt text e nome acessível
+
+- **Imagem informativa:** o `alt` transmite a informação que a imagem carrega no contexto ("Gráfico: vendas cresceram 12% de setembro a outubro"), não a descrição da foto ("gráfico azul"). Imagem com texto tem o texto no `alt`.
+- **Imagem decorativa:** `alt=""` (vazio, presente), para o leitor de tela pular.
+- **Imagem que é link ou botão:** o `alt` diz o destino ou a ação.
+- **Nome acessível igual ao rótulo visível:** o nome que o leitor de tela anuncia contém o rótulo visível, de preferência começando por ele (quem usa comando de voz diz o que vê: "clicar Salvar alterações"). Um botão que mostra "Salvar" e anuncia "Enviar formulário" quebra isso.
+- Pontuação, cor ou ícone sozinhos não carregam a mensagem.
+
+## Protótipo não é publicação
+
+Protótipo, composição ou mock não é código integrado nem autorização para publicar conteúdo. Canvas ou geração externa entram só quando o pedido exige e a ferramenta está disponível, com contexto mínimo e não sensível. Imagens temporárias seguem a política de retenção do projeto.