@andespindola/crow-skills 0.41.0 → 0.42.0

package/skills/crow-design/references/documento-do-sistema.md

@@ -0,0 +1,175 @@
+<!-- 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. -->
+# Documento do sistema (DESIGN.md) e documento de direção provisório
+
+Leia quando for registrar as decisões visuais que o contrato tomou: fixar o mundo escolhido antes da implementação (documento de direção provisório) ou o sistema que o contrato define (DESIGN.md normativo), e atualizá-lo por decisão versionada.
+
+**Fronteira.** O documento da crow-design nasce da **decisão**, não da leitura do código. Documentar um sistema que já existe no código, produzindo o DESIGN.md dele por extração, é da `crow-interface` (playbook de documentação); quando o pedido é esse, encaminhe para ela. A crow-design consome esse DESIGN.md como autoridade visual quando ele existe (ver [redesign e sistemas existentes](redesign-e-sistemas-existentes.md)).
+
+## Dois documentos, dois momentos
+
+- **Documento de direção provisório** (por exemplo `direcao.md`, nome em ASCII para evitar problemas de normalização em sistemas de arquivos e URLs): escrito **antes** do build, quando o mundo foi escolhido mas os valores ainda não foram provados na interface. Guarda o mundo comprometido, seus invariantes e as decisões em aberto. Não é normativo: o build pode contradizê-lo, e a contradição é informação.
+- **DESIGN.md normativo**: escrito quando o contrato define o sistema (tokens validados, papéis, regras nomeadas) e conferido contra o que foi construído. É o que outras sessões e outras pessoas seguem.
+
+O motivo da separação: um livro de regras escrito antes do build acaba sendo defendido contra a realidade em vez de descrevê-la, e dá ao revisor um alvo instável. O documento provisório é promovido a DESIGN.md quando o contrato fixa o sistema: compare o construído com o provisório, decida com o dono o que vale e registre no changelog o que mudou. Se a promoção exigir extrair valores do código pronto, essa extração é da `crow-interface`; a crow-design decide o que dela vira norma. Uma extensão comum dentro de um mundo estabelecido não reescreve o DESIGN.md; mudança durável no sistema é decisão aprovada, com versão.
+
+O DESIGN.md é estritamente visual. Verdade do produto, usuários e voz ficam no contexto de produto (ver [leitura do brief](leitura-do-brief.md)); estratégia de uma superfície e o contrato de direção ficam no brief da superfície. Do contexto de produto, o documento só carrega o que restringe o visual de fato: um logo vinculante, uma necessidade de acessibilidade, um compromisso de marca.
+
+## Quando escrever
+
+- Um mundo novo foi escolhido e ainda não há código: documento de direção provisório (modo seed, abaixo).
+- O contrato definiu ou mudou o sistema (tokens, papéis, regras): DESIGN.md normativo, com versão e changelog.
+- A primeira implementação de um mundo novo terminou e as decisões provisórias precisam ser fixadas.
+
+Fora daqui: existe um sistema coerente no código e nenhum documento, o documento está desatualizado em relação ao código, ou é preciso capturar o estado atual antes de um redesign. Nesses casos o documento é produzido a partir do código pela `crow-interface`; a crow-design lê o resultado e decide o redesign.
+
+Se um DESIGN.md já existe, **não o sobrescreva sem perguntar**: mostre o atual e pergunte se é para atualizar, substituir ou mesclar.
+
+## Frontmatter
+
+Camada legível por máquina. Cada entrada corresponde a um token que o projeto usa de fato; escala vazia ou token inventado polui a especificação. O formato da crow-design **estende o DESIGN.md comum** com `version` e `modes` e com `colors` por modo, mantendo compatibilidade: ferramentas que leem só o formato comum recebem, como fallback, `colors` plano com o modo padrão (detalhe abaixo).
+
+- `name`: título do projeto.
+- `description`: uma linha.
+- `version`: semver do sistema, igual ao `$meta.version` do arquivo de tokens.
+- `modes`: lista dos modos existentes (por exemplo `[light, dark, high-contrast]`), decididos com o dono.
+- `colors`: um mapa por modo; dentro de cada modo, um slug descritivo por cor (`canvas`, `ink`, `action`, não `blue-800`), no espaço de cor que o projeto trata como canônico (OKLCH em paleta nova; hex, `rgb()` ou `hsl()` incumbentes preservados). Todo slug existe em todos os modos.
+- `typography`: um objeto por papel (`display`, `headline`, `title`, `body`, `label`, e `caption` e `code` quando existem; os cinco primeiros são os do DESIGN.md comum, e os mesmos sete papéis nomeiam os semânticos de tipografia em [sistema de tokens](sistema-de-tokens.md)), cada um com os sete campos possíveis, só os reais para o projeto: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`.
+- `rounded`: os passos de raio que o projeto usa, com os nomes que ele já usa.
+- `spacing`: idem para espaço.
+- `components`: uma entrada por variante, com variantes como chaves irmãs (`button-primary`, `button-primary-hover`, `button-ghost`), usando só estas propriedades: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Valores por referência: `{colors.action}`, `{rounded.md}`, `{typography.label}`. Referência de cor omite o modo e resolve no modo ativo. Componentes referenciam os papéis semânticos do frontmatter (`colors`, `typography`, `rounded`, `spacing` nomeados por papel), nunca um valor cru; os grupos de papel não se referenciam entre si.
+
+Sombra, anel de foco, movimento, `backdrop-filter`, breakpoints e camadas não cabem no frontmatter: ficam no arquivo de tokens ([sistema de tokens](sistema-de-tokens.md)) e são descritos na prosa da seção pertinente. Ferramentas que leem só o formato comum do DESIGN.md aceitam `colors` como mapa plano e ignoram `version` e `modes`; se o projeto depende de uma delas, use o fallback: `colors` plano com o modo padrão, e a seção Colors diz onde estão os outros modos (o arquivo de tokens).
+
+**Artefatos.** O artefato legível por máquina daqui é o JSON de tokens validado ([sistema de tokens](sistema-de-tokens.md)). O sidecar `design.json` das origens não é produzido pela crow-design: ele é artefato da documentação a partir do código, da `crow-interface`.
+
+**Uma fonte de verdade.** Quando existe arquivo de tokens validado, ele é normativo e o frontmatter é gerado dele ou conferido contra ele; quando não existe, o frontmatter é a fonte. Nunca duas fontes editadas à mão, e nunca um valor repetido na prosa com número diferente do frontmatter.
+
+## Corpo: oito seções, nesta ordem e com estes nomes
+
+Os títulos ficam exatamente assim, em inglês, porque ferramentas fazem parsing deles; a prosa é no idioma do projeto. Seção irrelevante é omitida, não preenchida com regra inventada; as presentes ficam na ordem.
+
+1. **`## Overview`** — abre com a **North Star**: uma metáfora nomeada para o sistema inteiro, entre aspas. Depois, dois ou três parágrafos sobre personalidade, densidade e filosofia estética, partindo da North Star; só rejeições visuais confirmadas. Fecha com uma lista curta de características-chave.
+2. **`## Colors`** — uma frase sobre o caráter da paleta; cores agrupadas por papel (Primary, Secondary, Tertiary, Neutral), nunca por ordem de matiz. Com um acento só, existem Primary e Neutral; Secondary e Tertiary são omitidas, não inventadas. Cada cor com nome descritivo, valor exato entre parênteses e onde e por que é usada. Diga a estratégia de cor (contida, comprometida, paleta cheia, encharcada) e os pares de contraste por modo.
+3. **`## Typography`** — família display, de corpo e de rótulo ou código, cada uma com fallback e licença; uma ou duas frases sobre o caráter do par; hierarquia Display, Headline, Title, Body, Label com peso, tamanho, entrelinha e, no corpo, a medida (45–75ch, alvo 60–70ch).
+4. **`## Layout`** — modelo espacial (grade, colunas), **decisão de largura** por tipo de superfície (largura total em produto; contêiner só onde a composição pede), densidade, ritmo de espaçamento, comportamento responsivo e pontos de colapso. Valores exatos só quando observados ou decididos.
+5. **`## Elevation & Depth`** — sombra, camadas tonais ou híbrido; se não há sombra, diga como a profundidade é comunicada. Vocabulário de sombras com o `box-shadow` exato de cada papel e quando usar; escala de camadas.
+6. **`## Shapes`** — estratégia de raio (com a regra concêntrica), bordas, recortes, silhuetas recorrentes.
+7. **`## Components`** — por componente, uma linha de caráter e depois forma, cor, estados e comportamento: Buttons (forma, primário, hover e foco, secundário e ghost), Chips quando usados (estilo, selecionado e não selecionado), Cards e contêineres (raio, fundo, estratégia de sombra, borda, padding interno), Inputs e campos (traço, fundo, raio, foco, erro, desabilitado), Navigation (estilo, tipografia, estados, tratamento móvel) e, se houver, o componente-assinatura. Só componentes que existem.
+8. **`## Do's and Don'ts`** — guarda-corpos concretos, cada um começando por "Do" ou "Don't" (ou "Faça" e "Não faça"), com valores exatos quando estabelecidos, vindos do sistema real ou de uma escolha do dono. Uma recusa local de uma tarefa não vira proibição do sistema.
+
+Depois das oito, duas seções próprias deste pacote (o formato preserva seções extras):
+
+- **`## Exceções registradas`** — cada exceção a um default recusável ou a uma regra do sistema: o quê, por quê, quem aprovou, escopo, validade (data ou versão) e plano de saída. É aqui que fica registrado, por exemplo, que a fonte da marca está numa lista de "evitar como default" e continua.
+- **`## Changelog`** — por versão: adicionado, alterado, depreciado, removido, com motivo e, em mudança de cor, a razão de contraste resultante.
+
+## Estilo de escrita
+
+- **Frontmatter primeiro, prosa depois:** tokens no frontmatter, a prosa diz onde e por quê.
+- **Descritivo antes do técnico, valor entre parênteses:** "cantos levemente arredondados (8px)" em vez de `rounded-lg`; "verde-azulado profundo (`oklch(0.42 0.058 195)`)".
+- **Funcional antes de decorativo:** cada token explica onde e por que é usado.
+- **Regras nomeadas:** "**A Regra X.** doutrina curta (valor exato)". De uma a três por seção; são mais fáceis de citar e de seguir que listas. Exemplo: "**A Regra da Ação Única.** Cada tela tem uma ação preenchida com `action`; as demais são ghost ou texto."
+- **Decidido onde a evidência é decisiva:** linguagem firme para invariantes reais, linguagem branda para orientação provisória. Teste concreto de auditoria só quando ancorado no sistema observado ou numa decisão do dono; uma frase de teste vale mais que um parágrafo de princípio.
+
+## Perguntas qualitativas
+
+A linguagem qualitativa não sai dos tokens: em até duas rodadas de no máximo três perguntas, aguardando entre elas, combine com o dono a North Star (ofereça duas ou três opções coerentes com a direção), a voz do Overview (adjetivos de clima, filosofia em duas ou três frases, antirreferência confirmada), os nomes descritivos das cores principais, a filosofia de elevação e a de componentes. Mostre o documento inteiro, destaque as escolhas não óbvias e ofereça revisão por seção.
+
+## Modo seed (ainda não há código)
+
+Pré-requisito: contexto de produto existente e uma primeira superfície concreta. O seed vem da direção escolhida (ver [direção estética](direcao-estetica.md)) e é escrito como **documento de direção provisório**, não como DESIGN.md:
+
+- primeira linha com o marcador `<!-- SEMENTE: definido com o dono antes da implementação; promover a DESIGN.md quando o contrato fixar o sistema -->`;
+- frontmatter só com `name` e `description`;
+- mesmas oito seções, na mesma ordem: Overview com a tese, o comportamento de layout, o caráter material, a postura de imagem, a gramática de movimento e a assinatura reutilizável; Colors com a estratégia e os papéis; Typography com o caráter e a relação entre papéis; Layout com a gramática espacial; Elevation & Depth com o comportamento material como invariante; Shapes com a linguagem de forma; **Components omitida**; Do's and Don'ts com os guarda-corpos confirmados na escolha do mundo;
+- valores, nomes de fonte e cores só quando o dono, um asset existente ou a exploração os estabeleceram; o resto fica explícito como `[a resolver na implementação]`;
+- a composição da primeira superfície fica no brief dela, não sobe para o mundo global.
+
+## Armadilhas
+
+- Não colar nomes de classe crus; traduzir para linguagem descritiva com o valor entre parênteses.
+- Não normatizar one-off; parar no que é reutilizado.
+- Não inventar componentes. Se o projeto só tem botões e cards, só eles entram. Se existe um catálogo legível por máquina ao lado do documento e ainda não há componente, ele fica explicitamente vazio (`components: []`); nada de sintetizar "primitivos canônicos" para ter o que mostrar.
+- Não sobrescrever um DESIGN.md existente sem perguntar.
+- Não duplicar o contexto de produto: o documento é visual.
+- Não renomear nem trocar seções por sinônimos ("Color Palette & Roles" no lugar de "Colors").
+- Não duplicar valores entre frontmatter e prosa; a prosa nomeia e descreve, o frontmatter fixa.
+- Não criar grupos novos no topo do frontmatter (`motion:`, `shadows:`, `breakpoints:`); isso vive no arquivo de tokens.
+
+## Exemplo sintético
+
+Um sistema neutro de uma ferramenta interna de inventário (modo Operar), com os valores do [template de tokens](../templates/tokens.exemplo.json). É ilustrativo, não modelo de estética.
+
+```markdown
+---
+name: Inventário
+description: Ferramenta interna de contagem e reposição de estoque.
+version: 1.2.0
+modes: [light, dark]
+colors:
+  light:
+    canvas: "oklch(0.98 0.004 240)"
+    raised: "oklch(1 0 0)"
+    ink: "oklch(0.21 0.008 240)"
+    ink-muted: "oklch(0.4 0.012 240)"
+    action: "oklch(0.42 0.058 195)"
+    on-action: "oklch(1 0 0)"
+  dark:
+    canvas: "oklch(0.15 0.006 240)"
+    raised: "oklch(0.21 0.008 240)"
+    ink: "oklch(0.98 0.004 240)"
+    ink-muted: "oklch(0.85 0.01 240)"
+    action: "oklch(0.82 0.085 195)"
+    on-action: "oklch(0.15 0.006 240)"
+typography:
+  body:
+    fontFamily: "system-ui, sans-serif"
+    fontSize: "1rem"
+    fontWeight: 400
+    lineHeight: 1.5
+  label:
+    fontFamily: "system-ui, sans-serif"
+    fontSize: "0.875rem"
+    fontWeight: 600
+    lineHeight: 1.25
+    fontFeature: "\"tnum\" 1"
+rounded:
+  sm: "0.25rem"
+  md: "0.5rem"
+spacing:
+  "2": "0.5rem"
+  "4": "1rem"
+components:
+  button-primary:
+    backgroundColor: "{colors.action}"
+    textColor: "{colors.on-action}"
+    typography: "{typography.label}"
+    rounded: "{rounded.md}"
+    padding: "0.5rem 1rem"
+    height: "2.5rem"
+---
+
+# Design System: Inventário
+
+## Overview
+
+**North Star: "A Bancada de Contagem"**
+
+Uma superfície de trabalho plana e previsível, em que o número é o protagonista...
+
+## Colors
+
+Neutros frios levemente tingidos e um único verde-azulado de ação (estratégia contida).
+
+### Primary
+- **Verde-azulado de Ação** (`action`): botões primários e item selecionado; nunca decorativo.
+
+### Neutral
+- **Canvas Frio** (`canvas`): fundo de todas as telas.
+- **Tinta** (`ink`): texto principal; 4.5:1 ou mais sobre `canvas` e `raised` nos dois modos.
+
+**A Regra da Ação Única.** Cada tela tem uma ação preenchida com `action`; as demais são ghost ou texto.
+
+## Changelog
+
+- 1.2.0: adicionado o modo escuro; pares de contraste verificados nos dois modos.
+```

package/skills/crow-design/references/layout-e-espaco.md

@@ -0,0 +1,134 @@
+<!-- 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. -->
+# Layout e espaço
+
+Leia quando o contrato for decidir escala de espaçamento, densidade, grade, largura (total ou contida), altura, composição do primeiro viewport, navegação, seções de marketing, overlays, breakpoints ou ordem de leitura.
+
+## Escala e ritmo
+
+**Base 4.** Os degraus principais são 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 (px, expressos em `rem` no token). A base 4 dá degraus intermediários (12, 20, 28) que a base 8 não tem e que fazem falta em controles compactos e em ajustes ópticos. Escala completa de referência: 0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, 80, 96, 128, 160, 192. O contrato lista os passos que realmente usa, não a escala inteira; valores fora dela só entram como correção óptica documentada.
+
+**Semânticos separam a decisão do valor:** espaço de componente (4, 8, 12, 16), de seção (pela tabela canônica de densidade, abaixo), margem lateral da página e espaço vertical da página. Esses semânticos variam com o token de densidade, e nenhuma tela usa o primitivo direto.
+
+- **Grupos apertados, separação generosa.** O que pertence junto fica próximo; o que é outro assunto fica claramente longe. A diferença entre os dois intervalos é o que comunica a estrutura, não o valor absoluto de cada um.
+- **Mais espaço acima do título do que abaixo.** O título pertence ao conteúdo que vem depois dele; espaço igual dos dois lados deixa o título flutuando entre duas seções.
+- **Ritmo pelo contraste entre intervalos.** Uma página em que tudo está a 24px de tudo não tem ritmo; alternar intervalos curtos (dentro do grupo) e longos (entre grupos) cria leitura.
+- **Proximidade antes de contêiner.** Antes de desenhar uma caixa em volta de algo, tente agrupar só com espaço; borda e fundo são o segundo recurso, não o primeiro (ver [superfície e profundidade](superficie-e-profundidade.md)).
+- **`gap` entre irmãos.** Espaço entre itens de uma lista, grade ou pilha vem do `gap` do pai, não de margem em cada filho; margem no filho vaza quando o componente é reutilizado em outro contexto.
+- **Grade em vez de larguras calculadas.** `grid-template-columns` com `gap` substitui larguras como `calc(33% - 1rem)`, que quebram quando muda o número de itens ou o espaçamento.
+
+**Padding de seção por token de densidade**, nunca um valor fixo para todas as seções. A tabela canônica está em [sistema de tokens](sistema-de-tokens.md) (padding vertical de seção por DENSIDADE): 1–3, arejada, 128–192px (8–12rem); 4–7, padrão, 64–96px (4–6rem); 8–10, cockpit, 24–48px. O registro premium usa a faixa arejada, e uma tabela ou formulário dentro dele mantém a densidade da tarefa (ver [registro premium](registro-premium.md)).
+
+O que não muda: um único conjunto de tokens de densidade por superfície, sem valor solto por seção e sem padding mínimo fixo "para toda seção", que ignora a densidade. Em produto denso, cards genéricos somem e a separação vem de linhas e alinhamento; números alinham por algarismos tabulares, não por fonte monoespaçada.
+
+## Grade por faixa de variância
+
+O botão de variância (1 a 10) é derivado do brief e declarado na leitura (ver [leitura do brief](leitura-do-brief.md)). As faixas orientam a composição:
+
+- **1–3:** grade simétrica de 12 colunas, paddings iguais, alinhamento previsível. É o certo para produto, setor público, fluxo transacional e documentação, onde a previsibilidade é a função.
+- **4–7:** sobreposições moderadas (um elemento invadindo a seção anterior em cerca de 2rem), proporções de mídia variadas lado a lado (4:3 ao lado de 16:9), títulos alinhados à esquerda sobre dados centrados.
+- **8–10:** masonry, colunas desiguais como `grid-template-columns: 2fr 1fr 1fr`, recuos grandes de início de linha (da ordem de 20vw, sempre com `padding-inline-start`, nunca `padding-left`).
+
+**Colapso estreito.** De 4 a 10, abaixo do ponto em que a composição deixa de caber (768px é o exemplo mais comum, não a regra), toda a composição vira uma coluna em largura total com padding lateral de 16px e vertical de 32px: sobreposição, rotação, margem negativa e recuo grande saem, porque no toque eles criam conflito de alvo e corte de conteúdo. O contrato declara o colapso de cada seção.
+
+## Anti-centro
+
+Com variância acima de 4, o hero centralizado (título, subtítulo e botões empilhados no eixo do meio sobre um fundo) não é o default: é a composição que qualquer brief produz. Alternativas: divisão 50/50, conteúdo à esquerda com mídia à direita, espaço em branco assimétrico, seção fixada na rolagem.
+
+Cede quando o centro é a ideia: manifesto editorial, anúncio de lançamento, página de uma frase só, convite. Também não se aplica a Ler, onde a coluna de leitura centrada é correta, nem a Operar, onde a pergunta é outra.
+
+## Primeiro viewport e hero
+
+O primeiro viewport é a tese da superfície. Teste da memória: o que a pessoa descreveria uma hora depois? Se a resposta é "um título e dois botões", a tese não foi escrita. Uma página de marketing termina num fechamento real (a ação, a prova final), não numa sequência de seções que só para.
+
+Heurísticas de hero, cada uma com o motivo e o escape:
+
+- **Cabe no viewport.** Título, subtexto e ação primária visíveis sem rolar no desktop comum e no celular. Motivo: a ação que não se vê não existe para quem decide no primeiro olhar. Cede em Experienciar, quando o primeiro viewport é deliberadamente só imagem ou movimento.
+- **Título em até duas linhas no desktop.** Três já pede revisão; quatro linhas é erro de tamanho de fonte, não de texto (ver [tipografia](tipografia.md)).
+- **Subtexto curto por medida visual:** até três ou quatro linhas na medida do subtexto. A origem fala em 20 palavras; em português e alemão o texto cresce 30 a 40%, então o limite é de linhas e largura, não de contagem.
+- **Ações visíveis:** uma primária e no máximo uma secundária, em uma linha no desktop, rótulo curto.
+- **No máximo quatro elementos de texto:** um rótulo acima do título **ou** uma faixa de marca **ou** nenhum; título; subtexto; ações. Tagline abaixo do botão, micro-faixa de confiança, teaser de preço, bullets de feature e fileira de avatares vão para a seção seguinte. Motivo: cada elemento extra divide a atenção que o título precisa.
+- **Logos de clientes abaixo do hero**, nunca dentro, e só com relação comprovada (ver [texto e conteúdo](texto-e-conteudo.md)).
+- **Padding superior contido:** da ordem de 96px (6rem) no máximo no desktop, descontando a nav. Hero que começa no meio da tela empurra a ação para baixo da dobra.
+- **Altura com `dvh`/`svh`:** `min-height: 100dvh` (ou `svh` para o que não pode pular quando a barra do navegador móvel aparece), descontando o cromo fixo (header fixo, barra inferior). Nunca `100vh` nem `h-screen` em altura cheia: no celular escondem o rodapé do hero atrás da barra de endereço, e no Safari do iOS a barra dinâmica faz a página saltar. Vale para qualquer seção de altura cheia, não só o hero.
+
+Essas são heurísticas registradas e revisadas, não gates; o que bloqueia são contraste, foco, alvos e conteúdo honesto (ver [aceite e pré-voo](aceite-e-pre-voo.md)).
+
+## Navegação
+
+- **Uma linha no breakpoint grande** (por volta de 1024px). Nav que quebra em duas linhas no desktop é excesso de itens ou rótulos longos; resolva agrupando, não diminuindo a fonte.
+- **Altura de 64 a 72px como padrão**, até cerca de 80px. Acima disso a nav come o primeiro viewport.
+- **Padrão escolhido pela arquitetura de informação e pelo conteúdo.** Nav fixa de ponta a ponta é legítima e acessível; ilha flutuante em pílula funciona com poucos itens curtos e estoura com muitos itens ou com tradução. Em produto, os padrões consagrados são permitidos e esperados: top bar com side nav, breadcrumbs, tabs e command palette.
+- Menu em overlay é disclosure ou diálogo; a especificação de acessibilidade canônica (rótulo, estado, foco, Esc, retorno de foco, fundo inerte) está em [componentes e estados](componentes-e-estados.md), na seção de menus, disclosure e navegação recolhida.
+
+## Bento
+
+- **Contagem exata:** N itens geram N células, sem célula vazia ou de enchimento.
+- **Ritmo:** uma célula maior ao lado de menores empilhadas (por exemplo, 8 colunas por 2 linhas ao lado de duas de 4 colunas), não seis linhas iguais de imagem à esquerda e texto à direita.
+- **Fundos diversos:** duas ou três células com imagem, cor da marca, padrão ou tint; o resto neutro. Todas iguais é grade de cards; todas diferentes é ruído.
+- No estreito, uma coluna com `gap` uniforme (24px é a referência).
+
+## Seções de marketing
+
+As regras desta seção valem para páginas de marketing. Produto, documentação e coleções repetem componentes do sistema de propósito, e essa repetição é consistência, não monotonia.
+
+- **Variedade com motivo.** Oito seções com a mesma estrutura cansam; como sinal, oito seções costumam pedir pelo menos quatro famílias de composição. É heurística de revisão, não contagem a cumprir: seções diferentes por obrigação são tão genéricas quanto iguais.
+- **Zigzag no máximo duas vezes seguidas.** Imagem e texto alternando lado por três ou mais seções é o template mais reconhecível que existe; na terceira, troque de família.
+- **Split-header é default recusável:** título grande à esquerda (7 ou 8 colunas) com parágrafo pequeno à direita (4 ou 5) é a abertura de seção de todo template. A alternativa padrão é empilhar, com o corpo na medida de leitura. Cede quando o parágrafo é de fato uma nota lateral e a marca usa a estrutura.
+- **Forma padrão de seção:** um título curto, um subtítulo curto e um asset **ou** uma ação. O limite é medido em linhas e largura, não em palavras, por causa da tradução.
+- **Sem despejo de dados:** em marketing, os 3 a 5 itens principais e um link para a lista completa; lista com mais de cinco itens pede outro componente (duas colunas agrupadas, grade, tabs, accordion, pílulas com `scroll-snap`, carrossel).
+- **Ficha técnica sem borda em toda linha:** borda superior e inferior em cada linha de especificação vira planilha. Alternativas: grade de duas colunas com o valor em destaque e uma linha de "por que importa", grupos com um divisor só, ou destaques com disclosure para o resto.
+- **Sem três cards iguais lado a lado** como estrutura de seção, nem card dentro de card.
+
+## Largura total ou contido
+
+Decisão explícita por superfície, registrada no contrato:
+
+- **Telas de app e produto: largura total**, sem coluna `max-width` centralizada. É o default do pacote para telas de app e produto, recusável com motivo registrado no contrato, e é o que aproveita o espaço de trabalho. A medida de leitura limita a prosa (cerca de 65ch), não a página: um painel de texto dentro da tela larga tem `max-inline-size` próprio; a tela não.
+- **Erro mais comum:** a coluna centralizada herdada do layout raiz que corta um hero que devia sangrar ou estreita uma tabela. O contrato diz qual contêiner vale em cada região e de onde ele vem; mídia de destaque e hero que devem sangrar sangram.
+- **Marketing:** contêiner só quando a composição pede (uma coluna editorial, um produto pequeno que flutuaria numa tela de 2560px), nunca herdado por acidente de um template. Quando existe, ele é token (`layout.container`), não um `max-w-7xl` espalhado.
+- **Documento e editorial:** coluna de leitura na medida, com notas e figuras podendo sair dela.
+
+## Densidade operacional
+
+Em Operar, a superfície abre na matéria de trabalho (indicadores, filtros, a tabela ou o editor, o estado e o contexto da tarefa), sem hero nem frase de campanha. Navegação padrão (barra superior com navegação lateral, breadcrumbs, abas, paleta de comandos) é virtude, não preguiça. A responsividade é **estrutural**: a side nav recolhe para rail e depois para menu, a tabela vira cards com rótulo por campo ou ganha rolagem horizontal com cabeçalho e primeira coluna fixos, painéis viram abas. Esconder colunas sem dar acesso ao dado é perda, não adaptação. Densidade é token (compacto, padrão, confortável) que move espaçamentos e alturas de linha juntos; detalhes de tabela em [dados e densidade](dados-e-densidade.md).
+
+## Overlays e a árvore de decisão
+
+Antes de abrir qualquer camada, desça esta árvore e pare no primeiro nível que resolve:
+
+1. **Inline:** o conteúdo ou a edição acontece no lugar (expandir a linha, editar o campo). Preferido sempre que cabe.
+2. **Disclosure:** mostra e esconde uma região na própria página (`<details>`, accordion, "mostrar mais").
+3. **Popover ou sheet:** camada leve, não modal, presa a um gatilho ou à borda; fecha ao clicar fora e com Esc, sem bloquear a página.
+4. **Modal:** só para interrupção real (confirmar perda irreversível, decisão que bloqueia o fluxo) ou para foco protegido (um formulário que não pode se misturar com o resto). Modal como primeira ideia costuma ser preguiça de layout.
+
+Overlays saem do contêiner: `<dialog>` com `showModal()`, a API de popover, `position: fixed` ou portal. Nunca dentro de um ancestral com `overflow: hidden` ou `transform`, onde são cortados ou presos ao lugar errado. `<dialog>` e popover vão para a camada superior do navegador e dispensam z-index.
+
+## Breakpoints e container queries
+
+- **Breakpoints vêm do conteúdo:** o ponto em que a linha fica longa demais, a grade aperta ou a nav não cabe. Valores como 640, 768, 1024, 1280 e 1536 (ou 320–767, 768–1023, 1024+) são exemplos de convenção, não regra; o contrato declara os seus.
+- **Mobile-first com `min-width`** é o padrão de escrita: o estreito é a base e cada breakpoint acrescenta.
+- **Classes de contexto,** para decidir o que muda: celular (uma coluna, navegação inferior ou recolhida, bottom sheets, corpo de 16px ou mais), tablet (duas colunas, mestre-detalhe), desktop (várias colunas, atalhos, menu de contexto; em produto, largura total), impressão e e-mail têm regras próprias em [adaptação](adaptacao.md).
+- **Container queries** para componentes que vivem em larguras diferentes (um card na coluna principal e na lateral). O componente reage ao espaço que tem, não ao tamanho da janela.
+- **Larguras de verificação:** além dos breakpoints, confira o contrato no celular estreito (cerca de 390px), no desktop comum (1280 a 1600px, com 1440 como referência) e numa tela muito larga, onde layouts de largura total revelam linhas de texto longas demais.
+
+## Propriedades lógicas e RTL
+
+Tudo que tem lado usa propriedades lógicas: `margin-inline-start`, `padding-inline`, `inset-inline-end`, `border-inline-start`, `text-align: start`. Em RTL o layout espelha sem regra extra. Ícones direcionais (setas, voltar, avançar, progresso) espelham; ícones que representam objetos do mundo (relógio, play de mídia em muitas convenções, logotipos) não. Recuo "à esquerda" no contrato vira "no início da linha".
+
+## Camadas (z-index)
+
+Nada de `z-index` arbitrário (`50`, `9999`): a escala de camadas é token com posições nomeadas, e a escala canônica está em [superfície e profundidade](superficie-e-profundidade.md). O que vai para a camada superior do navegador (`<dialog>` modal, popover) dispensa a escala, mas o contrato diz o que convive com ele (um toast precisa aparecer acima de um modal aberto?).
+
+## Correção óptica
+
+Depois que a composição existe, alinhe pelo olho e documente o ajuste: o triângulo de play desloca para a direita do centro geométrico; ícone ao lado de texto alinha pela altura de versal, não pela caixa; formas redondas e pontiagudas ultrapassam levemente a linha de base e o topo para parecerem do mesmo tamanho que as retas; aspas e pontuação penduradas na margem em títulos grandes. Correção óptica é ajuste fino registrado, não licença para valores fora da escala por toda parte.
+
+## Simplificar (distill)
+
+Quando a superfície faz coisa demais, o caminho é linear: um fluxo, uma coluna, barras laterais removidas, largura total. Escolha um alinhamento (início da linha ou centro) e mantenha em toda a superfície; alternar os dois a cada seção é o que faz uma página simples parecer desorganizada.
+
+## Checagem do contrato
+
+**Ordem e alvo.** A ordem do DOM e a ordem de foco acompanham a ordem visual; reordenar só com CSS (`order`, posicionamento de grade) cria um caminho de teclado que não corresponde ao que se vê. Alvo de interação utilizável mesmo quando a marca visível é pequena (ver alvos em [componentes e estados](componentes-e-estados.md)). Estouro horizontal no celular é falha, não ajuste fino.
+
+Antes de entregar, confira: ordem de leitura (de olhos semicerrados, o caminho primário aparece?), agrupamento, ritmo, estrutura, densidade, adaptação por contêiner e por viewport, e os extremos (um item e mil itens, texto curto e texto traduzido longo). A ordem do DOM acompanha a ordem visual. A execução e o julgamento da tela construída ficam com `crow-interface`.

package/skills/crow-design/references/leitura-do-brief.md

@@ -0,0 +1,158 @@
+<!-- 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. -->
+# Leitura do brief: superfície, modo, autoridade e perguntas
+
+Leia quando um pedido de design chega e ainda não está claro o que a superfície é, quem manda no visual, o que falta saber e que artefato guarda cada decisão. É o primeiro passo de qualquer contrato; a direção estética vem depois, em [direção estética](direcao-estetica.md).
+
+## Quem manda
+
+A precedência vale para todo o pacote e resolve qualquer choque entre fontes:
+
+1. Pedido explícito atual do dono.
+2. Brief.
+3. Marca e autoridade visual existente: documento do sistema, tokens, componentes, código publicado.
+4. Decisões deste contrato.
+5. Defaults da skill.
+
+Quando o brief contradiz um compromisso de marca registrado, isso é conflito a nomear (fonte de cada lado, opções com custo e risco, quem decide), não algo a resolver em silêncio. Toda lista de "evitar como default" (fontes, paletas, eyebrow, vidro, serifa) é recusável: o brief ou a marca liberam o item, e a exceção vai registrada com motivo no [documento do sistema](documento-do-sistema.md). Nenhuma camada libera o que quebra acessibilidade (contraste, foco, movimento reduzido, alvo) ou verdade (conteúdo fabricado com cara de real).
+
+Honrar o brief inclui honrar o que ele fixa mesmo quando é estética saturada: era, material, fonte e paleta pedidas explicitamente valem contra o aviso de padrão repetido. Desviar um brief claro para o gosto de quem desenha é falha, não refinamento. O contrário também vale: refinamento preserva identidade, comportamento, texto e tudo que está fora do escopo pedido; trocar texto factual ou acrescentar afirmação exige perguntar antes.
+
+## Classificar a superfície
+
+Quatro classes, porque cada uma muda densidade, estabilidade e quanto o visual pode falar:
+
+- **Produto denso:** painel, tabela, formulário, configuração, ferramenta interna, fluxo transacional. Abre na matéria de trabalho (indicadores, filtros, tabela, estado, contexto da tarefa), sem hero nem frase de campanha.
+- **Landing e marketing:** página de produto, campanha, evento, portfólio. Pode gastar a primeira tela em composição.
+- **Documento e editorial:** documentação, artigo, relatório, blog, central de ajuda. A leitura e a orientação mandam.
+- **Nativo:** app iOS, Android ou adaptativo. A decisão de direção fica aqui; as convenções de plataforma e a implementação seguem com `crow-native-mobile`. Web móvel é web, e um wrapper nativo em volta de web não muda a classe.
+
+Estética de marketing num painel é erro de classificação, não de gosto. Um mesmo produto costuma ter as quatro classes (site, app, documentação, app móvel), e cada superfície é classificada à parte.
+
+## Modo do visitante
+
+O modo vem da superfície, não da empresa nem do setor. Ele fica registrado só no brief da superfície, porque outra superfície do mesmo produto pode ter outro modo.
+
+- **Persuadir** (a pessoa decide e age). Exige: oferta inteligível e desejável na primeira tela, ação primária visível, uma prova que só este produto pode dar, ordem de leitura legível, gancho que cabe numa linha. Libera as estratégias de cor mais comprometidas e tipografia display fluida. Classe típica: landing e marketing.
+- **Operar** (a pessoa completa uma tarefa). Exige: a expressão nunca esconde tarefa, estado nem affordance conhecida; familiaridade é virtude e o defeito é estranheza sem propósito. Piso de cor contida, escala tipográfica fixa em rem com razão 1.125–1.2, movimento de 150–250ms só para estado, densidade guiada pelo dado e pela frequência de uso. Classe típica: produto denso.
+- **Ler** (a pessoa entende). Exige: compreensão e orientação intactas, medida de 45–75ch com alvo de 60–70ch, hierarquia que serve à navegação (sumário, âncoras, títulos que se escaneiam), escala fixa. Classe típica: documento e editorial.
+- **Experienciar** (a pessoa está dentro da obra). Exige: a obra lidera desde a primeira tela, a exploração tem caminho, movimento autoral é permitido com alternativa intencional para movimento reduzido. Classe típica: portfólio, campanha imersiva, peça cultural.
+
+Quando a superfície mistura modos (uma landing com calculadora, uma documentação com playground), o modo dominante decide a direção e o trecho do outro modo segue as exigências dele dentro da mesma linguagem visual.
+
+## Situação de autoridade visual
+
+Antes de inventar, descubra o que já é verdade. Leia documento do sistema, código representativo, tokens, componentes e assets. Uma das quatro situações se aplica:
+
+- **Redesign:** existe um mundo visual que o dono quer trocar. Preserve verdade do produto, conteúdo, função, restrições e compromissos explícitos de marca; o visual antigo é evidência do que o assunto é, não autoridade sobre o que ele vira. Detalhes em [redesign e sistemas existentes](redesign-e-sistemas-existentes.md).
+- **Mundo estabelecido:** existe identidade coerente e ela continua valendo. Herde-a. Uma seção, componente, feature ou estado dentro de uma superfície estabelecida herda essa superfície; nunca transforme uma adição local num exercício de identidade nova.
+- **Marca incompleta:** há logo, cor ou fonte, mas não sistema. Preserve os ativos confirmados e os traços reconhecíveis e expanda o sistema com o dono para esta superfície, registrando o que foi derivado.
+- **Sem autoridade visual:** greenfield de verdade. A direção é criada com o dono.
+
+**Ausência de DESIGN.md não é greenfield.** Uma identidade coerente que já está no código (custom properties, tema, componentes, páginas publicadas) é autoridade; documente essa identidade em vez de inventar uma substituta. O caminho para extraí-la está em [redesign e sistemas existentes](redesign-e-sistemas-existentes.md).
+
+## Explorar antes de perguntar
+
+Pergunta cara é pergunta cuja resposta estava no repositório. Antes da primeira rodada, varra: documentação, configuração de tema, rotas, papéis de usuário, logos e assets, provas reais (depoimentos com autorização, números medidos), sinais de acessibilidade já atendidos e o comando de desenvolvimento. Trate o que encontrou como hipótese, não como fato, e declare a hipótese de plataforma (web, iOS, Android ou adaptativa). Em monorepo, confirme se o contrato vale para o espaço compartilhado ou para um app filho antes de escrever.
+
+## Sinais do brief, em ordem
+
+Leia nesta ordem e puxe só o que se aplica; nenhuma regra dispara sozinha.
+
+1. **Tipo de página:** landing (SaaS, consumo, agência, evento), portfólio (dev, designer, estúdio), redesign (preservar ou refazer), editorial ou blog, e as superfícies de produto (painel, formulário ou fluxo transacional, documentação, configuração).
+2. **Palavras de vibe:** "minimalista", "calmo", "estilo Linear", "Awwwards", "brutalista", "premium de consumo", "estilo Apple", "lúdico", "B2B sério", "editorial", "de agência", "vidro", "dark tech". Cada uma desloca os botões de direção conforme a tabela em [direção estética](direcao-estetica.md).
+3. **Referências:** URLs, capturas, produtos e concorrentes citados. Referência indica barra de qualidade e família, não layout a copiar.
+4. **Público:** quem vê escolhe a estética, não o gosto de quem desenha.
+5. **Assets de marca existentes:** logo, cores, fontes licenciadas, fotografia própria, ilustração autoral.
+6. **Restrições silenciosas:** acessibilidade crítica, setor público, setor regulado, comércio que depende de confiança, produto infantil, uso em campo (sol, luva, uma mão), conectividade ruim. Elas vencem a preferência estética, mesmo quando o brief não as nomeia.
+
+Cada eixo do contrato pede um insumo próprio; se ele faltar e mudar a decisão, é ele que se pergunta: cor pede as cores de marca; movimento pede as restrições de desempenho e de dispositivo; ousadia pede o alvo e o que fica intocado; personalidade pede a amplitude emocional aceitável; texto pede o conhecimento e o estado emocional de quem lê; primeiro uso pede o momento de valor e o nível do usuário; adaptação pede plataformas e contextos de uso.
+
+## Leitura declarada
+
+Antes de qualquer valor, declare a leitura numa linha visível no contrato. Ela substitui qualquer raciocínio silencioso: quem lê vê de onde saiu a direção e pode corrigir.
+
+> Leitura: <tipo de página> para <público>, linguagem <vibe>, inclinada a <sistema ou família estética>; modo <Persuadir|Operar|Ler|Experienciar>; botões V/M/D = x/y/z.
+
+Se o dono fixou o registro (seguro ou ousado), ele vem logo abaixo, na mesma declaração. Exemplos sintéticos:
+
+- "Leitura: painel de estoque para operadores de armazém, linguagem utilitária e calma, inclinada a um sistema de componentes acessível com sem serifa de sistema; modo Operar; botões V/M/D = 3/2/7."
+- "Leitura: portfólio de designer de produto para recrutadores e fundadores, linguagem editorial contida, inclinada a CSS nativo com rolagem como narrativa; modo Experienciar; botões V/M/D = 8/7/3."
+- "Leitura: serviço de agendamento de vacina para a população geral, linguagem sóbria de serviço público, inclinada ao sistema governamental oficial; modo Operar; botões V/M/D = 3/2/5."
+
+## Regra de pergunta
+
+- **Uma pergunta só quando a leitura diverge de fato** do que o pedido sugere. Se a inferência é confiável, declare a leitura e siga; o dono corrige se quiser. Sem sondagem cerimonial nem questionário.
+- **Em descoberta com o dono** (superfície nova, mundo novo, pedido esparso), até três perguntas por rodada, aguardando a resposta entre rodadas. Uma rodada é o padrão; prompt muito esparso justifica pelo menos uma.
+- **Nunca pergunte valores de CSS** nem ofereça "estilos" prontos para escolher. Pergunte pelo que muda a decisão: propósito, público, prova, estado, restrição.
+- **Sem resposta:** a primeira rodada real é também o teste de que há alguém para responder. Só depois de erro ou silêncio vale inferir. A rodada obrigatória cai de antemão quando o host declara que não há quem responda (execução não interativa, agente chamado por script ou orquestrador): nesse caso, não pergunte; infira, rotule cada fato como inferido e avise isso já na primeira resposta.
+- Uma restrição visual vinculante trazida pelo dono numa conversa de produto (o logo é este, a cor de marca é esta) é registrada sem ser expandida em direção.
+
+### Perguntas por modo
+
+- **Persuadir:** quem precisa agir, o que essa pessoa deve passar a crer, que prova, conteúdo ou asset real sustenta essa crença.
+- **Operar:** qual a tarefa, que informação ela exige, quais estados importam, com que frequência acontece, sob que restrições.
+- **Ler:** qual a pergunta do leitor, de onde vem o material, como ele se estrutura, como a pessoa se localiza.
+- **Experienciar:** o que lidera, como a exploração se desdobra, qual interação ou transição importa.
+
+Em todos os modos: o que define sucesso, o que precisa ficar intocado e o que faria um resultado polido parecer errado.
+
+### Rodadas de descoberta
+
+Rodada 1 (escolha duas ou três, pelo que falta):
+
+- Para que serve a superfície e que problema resolve (o trabalho).
+- Quem chega, em que situação e com que estado de espírito.
+- Qual a ação primária e como se reconhece sucesso.
+- O que é unicamente verdadeiro aqui, que nenhum concorrente pode afirmar.
+
+Rodada 2 (quando a primeira não fechou o escopo):
+
+- Conteúdo real e suas faixas: mínimo, típico e máximo (um item e mil; título de três e de oitenta caracteres; nome curto e nome composto longo).
+- Estados: primeiro uso, vazio, carregando, erro, sucesso, permissão negada, estouro, usuário experiente.
+- Fidelidade, amplitude e interatividade esperadas desta entrega.
+- O que fica intocado e o que pareceria errado.
+- Restrições de plataforma, desempenho, acessibilidade e localização.
+
+Entre rodadas, sem questionário: afirme a leitura provável e convide a correção.
+
+## Brief de superfície
+
+Uma superfície (rota, tela, feature, artefato) recebe um brief curto em sete campos. Quando o contexto já está assentado, três a cinco itens bastam. O brief confirma e para: não contém código nem tokens.
+
+1. **Trabalho e público:** quem, em que situação, para quê.
+2. **Resultado e prova:** o que muda para a pessoa e como se demonstra.
+3. **Direção selecionada:** a direção comprometida e, quando houver, o contrato de direção (ver [direção estética](direcao-estetica.md)).
+4. **Escopo e limites:** o que entra, o que fica intocado.
+5. **Estados e faixas:** os estados da rodada 2 e as faixas de conteúdo.
+6. **Interação e layout:** caminho do visitante, ação primária, decisão de largura (total ou contida) e comportamento por classe de dispositivo.
+7. **Restrições e decisões abertas:** o que limita e o que ainda depende do dono, com quem decide.
+
+O brief aponta para o contexto de produto e para os tokens; não copia nenhum dos dois. Escopo, modo, público, trabalho, prova, restrições, direção, o momento memorável e as decisões abertas cabem nele; mais que isso é sinal de que algo pertence a outro artefato.
+
+## Contexto de produto durável
+
+O documento de contexto de produto é da `crow-interface` (init): é ela que o cria e o atualiza. A crow-design só o **consome** quando ele existe, antes da direção, porque a direção sem verdade de produto vira mood. Quando ele não existe e o trabalho vai além de um ajuste local, a crow-design não cria nem atualiza o arquivo: registra no próprio contrato o que precisou supor sobre os campos abaixo, rotulado como suposição, e aponta a `crow-interface` como dona do documento. Campos que ela procura nele:
+
+- **Usuários:** quem são, em que situação, com que trabalho a fazer.
+- **Trabalhos (jobs):** o que a pessoa contrata o produto para fazer.
+- **Propósito:** o que o produto possibilita e o mecanismo que o diferencia.
+- **Posicionamento:** contra o que e ao lado de quem ele se coloca.
+- **Contexto operacional:** onde, quando, em que dispositivo, sob que luz e pressão.
+- **Capacidades e restrições:** o que o produto faz e não faz hoje; limites técnicos, legais e de plataforma.
+- **Compromissos de marca:** o que é vinculante (logo, nome, cor, fonte licenciada, tom) e as escolhas declaradas do dono, inclusive a de executar o padrão da categoria.
+- **Evidência disponível:** provas reais com origem (depoimentos autorizados, métricas medidas, clientes com relação comprovada).
+- **Princípios do produto:** três a cinco, cada um capaz de desempatar uma decisão.
+- **Acessibilidade e inclusão:** público com necessidades declaradas, nível de conformidade, idiomas e scripts.
+
+Plataforma e stack entram quando conhecidas; num greenfield, a stack é decisão do dono (perguntada, ou registrada como delegada). Ficam **fora** do contexto de produto: mundo visual, modo, narrativa de página, chamada para ação e qualquer afirmação inventada (depoimento, cliente, benchmark, preço, licença, prazo de entrega). Essas coisas são do contrato ou não existem. A entrevista de produto não pergunta estética, emoção, referências, cores, tipo ou estilo.
+
+## Precedência entre artefatos
+
+Cada artefato decide uma coisa; nenhum invade o outro.
+
+- **Contexto de produto:** verdade do produto e voz.
+- **Documento do sistema (DESIGN.md e arquivo de tokens):** decisões visuais duráveis. O arquivo de tokens validado é normativo para valores; a prosa contextualiza. Formato em [documento do sistema](documento-do-sistema.md) e [sistema de tokens](sistema-de-tokens.md).
+- **Brief de superfície e contrato de direção:** estratégia de uma superfície (modo, direção, primeira tela). Não sobe para o sistema sem decisão explícita.
+- **design-contract:** o registro desta entrega (decisões, alternativas descartadas, evidência, pendências), conforme [o que o contrato decide](contrato.md).
+
+Sem documento do sistema, a identidade é lida do código como autoridade visual para decidir a direção (ver [redesign e sistemas existentes](redesign-e-sistemas-existentes.md)); produzir o DESIGN.md a partir do código é da `crow-interface`. Com documento desatualizado em relação ao código, o desencontro é relatado como drift, com evidência de contradição concreta (não contagem de commits), e o dono decide qual lado vale. Choques entre artefatos seguem a precedência do início deste arquivo.