nexus-core-v3 3.0.0

package/knowledge/web-craft/style-cloning.md

@@ -0,0 +1,185 @@
+---
+id: style-cloning
+domain: web-craft
+agents: [ux-design-expert]
+when: "ao receber uma referência (site/print) e precisar reaplicar a linguagem de design dela num novo projeto"
+---
+
+# Style Cloning — extrair a linguagem de uma referência e reaplicar fielmente
+
+O pedido chega assim: "faz parecido com esse site", junto de um print ou uma URL. O trabalho **não** é
+copiar a tela — é dissecar *por que* aquela referência funciona, isolar as decisões que dão o feeling, e
+reconstruir essas decisões como sistema no projeto novo. Quem copia a tela produz uma falsificação
+quebrada; quem extrai a **linguagem** produz algo que pertence à mesma família visual e ainda assim é
+próprio.
+
+**A linha ética é dura e vem antes de tudo:** você extrai a *técnica* (a razão tipográfica, a temperatura
+da paleta, a curva de easing, a densidade) — você **nunca** copia o asset (logo, foto, ilustração,
+ícone-set proprietário, o texto/conteúdo). Linguagem de design é craft e não é protegível; asset e copy
+são IP de terceiros. Se você se pegar baixando a imagem do hero da referência pra usar no projeto, parou:
+errado. Reproduza o *tratamento* daquela imagem (grão, corte, temperatura) numa imagem licenciada/própria.
+
+## O problema / os tells de uma clonagem ruim
+
+Reconheça o trabalho ruim — clonagem feita errado tem cara:
+
+1. **Print-tracing.** A pessoa recriou *aquela tela exata* (mesmo hero, mesma manchete, mesmos 3 cards na
+   mesma ordem) em vez de extrair o sistema. Resultado: muda o conteúdo do projeto e tudo desaba, porque
+   nada era regra — era cópia pixel a pixel de um caso específico.
+2. **"Pegou a cor primária" e mais nada.** Capturou `#FF5A1F` da referência, jogou num template default
+   e achou que clonou. A cor sozinha não carrega o feeling — carrega tipografia + espaço + densidade +
+   motion juntos.
+3. **Tipografia trocada pelo "parecido do Google Fonts".** A referência usa uma grotesca comercial paga;
+   a pessoa botou Montserrat "porque é tipo isso" e o caráter evaporou. Par de fonte errado mata a
+   semelhança mais que cor errada.
+4. **Eyedropper de uma cor, não da temperatura.** Pegou o accent mas manteve os neutros do template
+   (cinza `#888` puro), enquanto a referência tinha neutros quentes (cinza puxado pro bege). A página
+   "não fica igual" e ninguém sabe dizer por quê — é a temperatura dos neutros.
+5. **Densidade ignorada.** A referência é apertada e densa (estilo terminal/editorial, muita info por
+   tela); a réplica saiu arejada e espaçosa porque o template era assim. O *ritmo de informação* é
+   metade da identidade e foi perdido.
+6. **Motion copiado de olho como "fade".** A referência tem um stagger com easing custom e overshoot
+   sutil; a réplica botou `fade-up .3s ease` em tudo. O movimento é assinatura e foi achatado.
+7. **Asset roubado.** Baixou a foto/ilustração/ícone da referência e colou no projeto. Além de antiético
+   e ilegal, denuncia a cópia — é literalmente o material de outra marca na sua página.
+8. **Sem validação lado a lado.** Entregou "de memória", sem nunca colocar referência e réplica na mesma
+   tela pra comparar. Sempre que isso acontece, a réplica está 40% fora e a pessoa não percebeu.
+
+## Os princípios do craft
+
+### 1. Capture sete dimensões, não "a cara"
+
+O feeling de uma referência mora em sete eixos. Capture cada um **explicitamente** — anote número e nome,
+não impressão vaga. Use o DevTools (Computed styles) e um eyedropper; impressão "de olho" erra.
+
+- **Paleta + temperatura.** Não pegue só o accent. Pegue: 1 accent (e seu hover/active), 2–3 neutros
+  (background, surface, texto) e diga a **temperatura** de cada um. O segredo costuma estar nos neutros:
+  `#F7F5F2` (off-white quente) sente-se completamente diferente de `#FFFFFF` puro, e é isso que dá o "ar
+  premium/editorial". Anote em HSL pra ler a temperatura: se o H dos cinzas está em ~30–50 são quentes,
+  ~200–220 são frios, sem saturação são mortos.
+- **Sistema tipográfico.** O *par* (display + texto), a **razão da escala** (meça dois tamanhos
+  consecutivos e divida: 64/48 ≈ 1.33; 18/16 = 1.125 — descubra a razão), o **peso** de cada nível, o
+  **tracking** do display (geralmente negativo em manchete grande: `-0.02em` a `-0.04em`) e o **leading**
+  (1.05–1.15 em manchete, 1.5–1.65 em corpo). Identifique as fontes reais (WhatFont, ou olhe o
+  `font-family` no Computed). Se forem pagas, escolha o substituto pelo **caráter** (mesma classe:
+  grotesca-de-contraste, serifa-transicional, mono-humanista), não pelo nome parecido.
+- **Escala de espaço.** Meça gaps e paddings reais. Existe uma base e uma razão? (8/16/24/40/64 é linear
+  ×8; 4/8/16/32/64 é geométrico ×2 — sentem diferente). Anote os **extremos** que a referência usa: qual
+  o menor gap de agrupamento e o maior respiro de seção. A relação entre eles é o ritmo.
+- **Raios + sombras.** Raio do botão, do card, do input — são iguais ou variados por propósito? Sombra:
+  é uma `shadow-md` genérica ou uma sombra **longa e suave de baixa opacidade** (`0 20px 40px
+  rgba(0,0,0,.06)`)? Borda de 1px hairline em vez de sombra? Isso define "macio" vs "nítido".
+- **Densidade.** Quanta informação por tela? Conte: a referência mostra 3 coisas com muito ar, ou 12
+  coisas organizadas e densas? Densidade é decisão de identidade — um Linear/terminal denso e um
+  Stripe/marketing arejado usam *a mesma* base de 8px com densidades opostas.
+- **Motion + easing.** Abra e role devagar. O que entra: tudo junto ou em **stagger**? A curva é o `ease`
+  default ou tem **overshoot/anticipation** (cubic-bezier custom)? Duração curta (120–200ms, ágil) ou
+  longa (400–600ms, cinematográfico)? Há scroll-linked/parallax? Anote a *sensação* (ágil vs preguiçoso
+  vs elástico) e tente a curva.
+- **Tom de imagem + voz da copy.** Imagem: foto ou ilustração? Quente ou fria? Tem **grão/ruído**?
+  Contraste alto ou lavado (faded)? Corte cheio ou minimalista? Voz da copy: manchetes curtas e secas?
+  Técnicas e específicas? Com humor? Em caixa baixa proposital? Essa é a *técnica* — você reaplica o
+  **tratamento**, com seus próprios assets e seu próprio texto.
+
+### 2. Traduza cada captura em token — o sistema é a ponte
+
+Captura solta vira cópia; captura virada **token** vira linguagem reaplicável. Para cada dimensão, escreva
+um token nomeado *pela intenção*, não pelo valor. É o token que se reaplica no projeto, não o print.
+
+```css
+:root {
+  /* temperatura é decisão, não acidente — neutros quentes */
+  --bg:        hsl(40 20% 97%);   /* off-white quente, não #fff */
+  --surface:   hsl(40 14% 94%);
+  --text:      hsl(30 8% 12%);
+  --accent:    hsl(18 90% 55%);   /* +hover/active derivados, não avulsos */
+
+  /* escala tipográfica: razão 1.25 capturada da referência */
+  --step-0: 1rem; --step-1: 1.25rem; --step-2: 1.563rem; --step-3: 1.953rem;
+  --display-tracking: -0.03em;    /* manchete aperta */
+  --display-leading: 1.08;
+  --body-leading: 1.6;
+
+  /* espaço: geométrico ×2, com extremos reais usados */
+  --s-1: .5rem; --s-3: 2rem; --s-6: 8rem;  /* respiro de seção grande */
+
+  /* superfície: sombra longa de baixa opacidade, não shadow-md */
+  --shadow-soft: 0 24px 48px -12px hsl(30 20% 10% / .08);
+  --radius-card: 14px;            /* nem 8 default, nem pill */
+
+  /* motion: curva com overshoot sutil, captura do easing */
+  --ease-signature: cubic-bezier(.16, 1, .3, 1);
+  --dur-quick: 160ms;
+}
+```
+
+Regra de ouro da tradução: **a razão e a temperatura viajam; os valores absolutos podem mudar.** Se o
+projeto novo precisa de accent azul por imposição da marca, mantenha a *mesma temperatura de neutros*, a
+*mesma razão tipográfica*, a *mesma densidade* e o *mesmo easing* — a família visual sobrevive à troca de
+cor. É por isso que se extrai sistema, não pixels.
+
+### 3. Reproduza o feeling, não os assets
+
+O feeling vem do **tratamento**, e tratamento é técnica reproduzível com material próprio:
+
+- A referência tem fotos com grão e contraste lavado? Aplique `filter` + um overlay de ruído + uma
+  curva de contraste **nas suas próprias fotos** (licenciadas/geradas/da marca). O grão é a técnica; a
+  foto é sua.
+- Ícones com aquele traço fino e cantos específicos? Use um set aberto (ou desenhe) com o *mesmo
+  stroke-width e o mesmo line-cap* — não baixe o set proprietário da referência.
+- Aquele detalhe gráfico recorrente (uma linha hairline entre seções, um numeral monoespaçado de label,
+  um sublinhado deslocado no link)? Esses "maneirismos" carregam mais identidade que o hero inteiro.
+  Catalogue-os e reaplique — são técnica pura, sem asset envolvido.
+- A estrutura/sequência das seções **não** se copia ("hero→logos→3 features→CTA" é justamente o tell de
+  template). Reproduza os *princípios de composição* (assimetria, ponto focal único, sangria) sobre o
+  *seu* conteúdo, na *sua* ordem.
+
+### 4. Valide fidelidade lado a lado, com checagem objetiva
+
+Nunca confie na memória. Coloque **referência e réplica na mesma viewport** (duas janelas, ou print da
+ref ao lado do localhost) e cheque eixo por eixo, não "no geral":
+
+- **Squint test** (aperte os olhos / desfoque 8px ambas): os blocos de peso e o ritmo claro-escuro batem?
+  Se a mancha geral diverge, é densidade ou hierarquia — não cor.
+- **Overlay de cor:** eyedropper no mesmo tipo de elemento (bg, texto, accent) nas duas. Bate o H/S/L?
+- **Régua na tipografia:** meça a razão entre H1 e corpo nas duas. Mesma razão? Mesmo tracking de
+  manchete?
+- **Cronômetro no motion:** role as duas devagar. Mesma sensação (ágil/elástico/lento)? Entra junto ou em
+  stagger nas duas?
+
+Se três dos quatro batem e o projeto ainda parece "seu" (assets e copy próprios), a clonagem da
+*linguagem* foi um sucesso e a do *conteúdo* não aconteceu — exatamente o objetivo.
+
+## Checklist
+
+Antes de entregar uma reaplicação de estilo, responda — qualquer "sim" da seção ÉTICA é bloqueio:
+
+**Ética (bloqueante):**
+- [ ] Algum asset da referência (foto, logo, ilustração, ícone-set, vídeo) foi baixado e usado?
+- [ ] Algum texto/copy da referência foi colado em vez de reescrito com voz própria?
+- [ ] A estrutura é uma cópia 1:1 da página da referência em vez de princípios reaplicados?
+
+**Captura (todas devem ter resposta concreta, com número/nome):**
+- [ ] Capturei accent **e** a temperatura dos neutros (em HSL), não só uma cor?
+- [ ] Identifiquei o par de fontes real e a **razão** da escala tipográfica (não chutei "Montserrat")?
+- [ ] Medi a escala de espaço e anotei os **extremos** (densidade) que a referência usa?
+- [ ] Capturei raio, tipo de sombra e o **easing/duração** do motion?
+
+**Tradução + fidelidade:**
+- [ ] Cada captura virou **token nomeado por intenção**, reaplicável no conteúdo do projeto?
+- [ ] Reproduzi o **tratamento** de imagem (grão/contraste/corte) em assets próprios?
+- [ ] Fiz o teste **lado a lado** com squint + overlay de cor + régua tipográfica + cronômetro de motion?
+- [ ] A réplica pertence à mesma família visual **e** usa conteúdo/assets inteiramente próprios?
+
+## Antes → depois
+
+| Clonagem ruim (o tell) | Clonagem de craft (a linguagem) |
+|---|---|
+| Recriou a tela exata da referência (mesmo hero, mesmos 3 cards, mesma ordem) | Extraiu razão tipográfica, temperatura, densidade e easing como tokens e reaplicou no conteúdo do projeto |
+| Pegou só o accent `#FF5A1F` e jogou no template default | Capturou accent **+** neutros quentes em HSL **+** sombra longa **+** razão 1.25 — o conjunto que dá o feeling |
+| Trocou a grotesca paga por "Montserrat porque é parecido" | Escolheu substituto pela **classe e caráter** (grotesca-de-contraste), com mesmo tracking negativo na manchete |
+| Manteve neutros `#888` do template sobre o accent da ref | Reproduziu a temperatura: `hsl(40 14% 94%)` de surface, off-white quente como a referência |
+| Página arejada porque o template era; ref era densa | Reproduziu a **densidade** real — mesma base de 8px, mesmo ritmo de informação por tela |
+| `fade-up .3s ease` em tudo de olho | Stagger com `cubic-bezier(.16,1,.3,1)` e 160ms — a curva e o tempo capturados da referência |
+| Baixou a foto do hero da referência e colou | Aplicou o **tratamento** (grão + contraste lavado + corte) numa foto própria/licenciada |
+| Entregou "de memória", 40% fora sem perceber | Validou lado a lado com squint + overlay + régua + cronômetro antes de entregar |

package/knowledge/web-craft/visual-polish-review.md

@@ -0,0 +1,183 @@
+---
+id: visual-polish-review
+domain: web-craft
+agents: [ux-design-expert, dev]
+when: "ao revisar o acabamento visual de uma UI antes de entregar"
+---
+
+# Visual Polish Review — auditar o acabamento antes de entregar
+
+## O problema
+
+Uma UI "funciona" e ainda assim parece amadora. Não é por falta de feature — é falta de
+**acabamento**: hierarquia construída só com tamanho de fonte, cinza puro em tudo, sombras
+opacas e chapadas, espaçamento linear sem ritmo, botão sem estado de hover, tela vazia que
+parece bug. Cada um desses é um **tell** que um olho treinado reconhece em meio segundo.
+
+Este pack é a régua que Adam Wathan e Steve Schoger (*Refactoring UI*) usam: ~10 lentes de
+auditoria, cada uma com **o tell** (o que denuncia o amador) e **a correção concreta** (o valor,
+a regra, o CSS). Não é "melhore a tipografia" — é "trave em 2 pesos: 400-500 pra corpo, 600-700
+pra ênfase; nunca abaixo de 400 em texto pequeno". A regra-mãe: **acabamento é um sistema de
+escolhas pré-definidas, não tweak avulso por elemento.**
+
+## O conhecimento
+
+### Lente 1 — Hierarquia por peso e cor, não só por tamanho
+
+**O tell:** todo destaque é "fonte maior". Títulos `font-size: 32px`, subtítulos `24px`, e a
+hierarquia inteira mora no eixo do tamanho. Resultado: telas que incham e ainda assim parecem
+planas.
+
+**A correção:** distribua a hierarquia em **três eixos** — tamanho, **peso** e **cor**.
+- Para texto, dois pesos bastam: **400–500** (corpo) e **600–700** (ênfase). Evite peso
+  **abaixo de 400** em texto de UI — só funciona em título grande, é ilegível em corpo.
+- Cor cria hierarquia **sem encolher a fonte**: escuro pro conteúdo primário, cinza pro
+  secundário (data, metadado), cinza mais claro pro terciário (rodapé, copyright).
+- **Emphasize by de-emphasizing:** às vezes o jeito de destacar um elemento é **apagar os
+  vizinhos**, não empilhar mais peso no elemento. Reduza o ruído ao redor primeiro.
+
+### Lente 2 — Tipografia: escala, line-height inverso, baseline
+
+**O tell:** `line-height: 1.5` em título grande (frouxo demais), tamanhos avulsos sem escala,
+textos de tamanhos diferentes alinhados pelo **centro**.
+
+**A correção:**
+- **line-height e font-size são inversamente proporcionais:** ~1.5 em corpo pequeno, e
+  **apertado** (1.1–1.2) em display grande. Título com line-height de corpo é tell.
+- Use uma **escala fixa** de tamanhos (escolha de uma lista, não digite valores arbitrários).
+  Defina `font-size` em **px ou rem**, não em `em` (em compõe e vira imprevisível aninhado).
+- Alinhe tamanhos mistos pela **baseline** (a linha onde as letras pousam), nunca pelo centro.
+- **Letter-spacing:** confie no designer da fonte na maioria dos casos; **aperte** títulos em
+  fontes de texto usadas grandes, e **solte** texto em ALL-CAPS.
+
+### Lente 3 — Medida (line length) controlada
+
+**O tell:** parágrafo que atravessa a tela inteira; texto longo **centralizado**.
+
+**A correção:** **45–75 caracteres por linha** (~`max-width: 20–35em` para o bloco de texto, ou
+uma `measure` ~`65ch`). Centralize só headline ou bloco curto independente — **texto corrido é
+left-align**, sempre.
+
+### Lente 4 — Cor em HSL, com cinzas que têm temperatura
+
+**O tell:** `#808080` e amigos — cinza puro, dessaturado, frio-morto. Cor escolhida em HEX no
+chute.
+
+**A correção:** pense em **HSL** (Hue 0–360°, Saturation 0–100%, Lightness 0–100%) — é como o
+olho enxerga.
+- **Cinza não precisa ser cinza:** sature com **azul** pra paleta fria, com **amarelo/laranja**
+  pra paleta quente. Cinza com 0% de saturação é o tell.
+- **Quanto mais longe de 50% de lightness, mais saturação** o tom precisa — aumente saturation
+  nos tons claros E escuros pra manter a temperatura constante ao longo da rampa.
+- **Nunca cinza sobre fundo colorido.** O efeito "cinza sobre branco" é só **contraste
+  reduzido**; sobre cor, escolha um tom de **mesmo hue** e ajuste S/L até aproximar do fundo.
+
+### Lente 5 — Paleta como sistema, não 3 cores soltas
+
+**O tell:** uma cor de marca, um cinza, preto e branco. Sem rampas — então todo hover/borda/
+disabled é inventado na hora.
+
+**A correção:** monte rampas com **~9 shades** (sweet spot) por cor:
+- **8–10 tons de cinza** (do quase-branco ao quase-preto).
+- **1–2 cores primárias**, 5–10 shades cada.
+- **Accent colors** (sucesso, erro, aviso, info), 5–10 shades cada.
+- Gradiente, quando usar: dois hues **a até 30° um do outro** (mais que isso fica "lama").
+
+### Lente 6 — Espaçamento NÃO-linear, com ritmo
+
+**O tell:** tudo em múltiplos de 8 sem variação — `gap-8`, `py-16` em toda seção. Espaço linear
+é monótono e robótico.
+
+**A correção:** escala **não-linear** onde **nenhum par de valores fica a menos de ~25%** um do
+outro. Exemplo de rampa: **4, 8, 12, 16, 24, 32, 48, 64, 96, 128**. Use os **extremos** — seção
+densa (prova social) ao lado de seção arejada (manifesto) cria ritmo. Heurística de processo:
+**comece com espaço demais e remova até gostar** — quase sempre falta whitespace, não sobra.
+
+### Lente 7 — Elevação em camadas (sombra de luz, não cinza opaco)
+
+**O tell:** `box-shadow: 0 2px 4px #ccc` chapado em tudo; mesma sombra no botão e no modal.
+
+**A correção:** uma **escala de ~5 sombras** mapeando elevação:
+- pequena → botão/elemento levemente elevado;
+- média → dropdown;
+- grande → modal (precisa puxar atenção).
+- Cada sombra combina **duas camadas**: luz **ambiente** (offset pequeno, blur menor, mais
+  escura) + luz **direta** (offset vertical maior, blur grande, difusa). Spread **negativo** dá
+  o efeito sutil quanto mais o objeto sobe. Ex.: `box-shadow: 0 25px 50px -12px rgba(0,0,0,.25)`.
+- Cor da sombra: **preto transparente** (rgba), não cinza opaco; idealmente um tom **escuro do
+  próprio hue** do fundo (sombra azul-escura sob botão azul), nunca `#888` chapado.
+
+### Lente 8 — Separação sem borda
+
+**O tell:** `border: 1px solid #ddd` em cada card, linha divisória em cada item. A tela vira
+uma grade de gaiolas.
+
+**A correção:** separe com **sombra, espaçamento ou cor de fundo** antes de recorrer a borda.
+Dois fundos levemente diferentes, ou só mais respiro entre os blocos, separam melhor e mais
+limpo que um traço. Borda fica pro caso em que sombra/espaço não bastam.
+
+### Lente 9 — Estados de botão completos
+
+**O tell:** botão tem só o estado **default**. Sem hover, sem active, sem focus visível (ou o
+anel azul do browser), sem disabled. Foco azul nativo é tell de "esqueci do detalhe".
+
+**A correção:** desenhe **todos os estados**:
+- **hover** — sobe de elevação (sombra um degrau acima) ou escurece/clareia um shade da rampa;
+- **active/pressed** — **reduz a sombra** pra sensação de "sendo pressionado";
+- **focus** — anel **desenhado** (`outline`/ring de marca), nunca o azul default;
+- **disabled** — contraste reduzido e cursor coerente.
+- **Hierarquia de ações na mesma tela:** primária óbvia; secundária clara mas não dominante
+  (fundo suave derivado da cor do texto); terciária descobrível mas discreta (link). Chevron no
+  link de texto reforça que é clicável.
+
+### Lente 10 — Empty states desenhados
+
+**O tell:** tela vazia = página em branco, ou um texto que parece **erro** ("Nenhum dado.").
+É a **primeira** interação do usuário com a feature e parece bug.
+
+**A correção:** trate empty state como **boas-vindas**: ilustração ou imagem + uma frase com voz
++ **um CTA claro** que ensina o próximo passo. Mesma régua pra 404 e estados de erro — microcopy
+com personalidade é assinatura barata e forte.
+
+### Bônus — Imagem que não vaza
+
+**O tell:** foto esticada (upscale), imagem de usuário com proporção quebrada, foto clara com
+texto branco ilegível por cima.
+
+**A correção:** só **reduza** imagem, nunca amplie. Controle dimensões de upload com
+`background-size: cover`. Sombra sutil na imagem evita que o fundo "sangre" na borda. Texto sobre
+foto: overlay (escurecer/colorir) pra garantir contraste.
+
+## Checklist — "isto está acabado?"
+
+Qualquer "sim" é um item a corrigir antes de entregar:
+
+- [ ] A hierarquia mora **só** no tamanho da fonte (sem variar peso e cor)?
+- [ ] Tem peso **abaixo de 400** em texto pequeno, ou `line-height ~1.5` em título grande?
+- [ ] Texto corrido passa de **75 caracteres** por linha, ou está centralizado?
+- [ ] Tem **cinza puro** (`#808080`/0% saturação) ou cinza sobre fundo colorido?
+- [ ] As cores são valores soltos, **sem rampas** de ~9 shades pra hover/borda/disabled?
+- [ ] O espaçamento é **linear/uniforme**, sem usar os extremos da escala?
+- [ ] A sombra é **cinza opaco chapado**, igual no botão e no modal?
+- [ ] A separação é feita com **borda** onde sombra/espaço/fundo bastariam?
+- [ ] Algum botão tem **só default** (sem hover/active/focus desenhado/disabled)?
+- [ ] O foco é o **anel azul do browser** em vez de um foco de marca?
+- [ ] O **empty state / 404** é página em branco ou parece mensagem de erro?
+
+## Tabela de decisão
+
+| Lente | O tell | A correção concreta |
+|---|---|---|
+| Hierarquia | Destaque só por tamanho | 3 eixos: tamanho + peso (400-500 / 600-700) + cor; de-emphasize o entorno |
+| Tipografia | line-height 1.5 em título; alinhar pelo centro | line-height inverso ao tamanho; escala fixa em px/rem; alinhar pela baseline |
+| Medida | Linha atravessa a tela; texto centralizado | 45–75 caracteres (~20–35em / ~65ch); corrido é left-align |
+| Cor (HSL) | `#808080`, cinza sobre fundo colorido | Sature o cinza (azul=frio, amarelo=quente); mesmo hue, ajusta S/L |
+| Paleta | 3 cores soltas, sem rampa | ~9 shades por cor; 8-10 cinzas; gradiente com hues a ≤30° |
+| Espaçamento | Tudo em múltiplos de 8 | Escala não-linear (≥25% entre valores: 4/8/12/16/24/32/48/64/96/128), usar extremos |
+| Elevação | Sombra chapada igual em tudo | Escala de ~5; 2 camadas (ambiente+direta); rgba escuro do hue, não cinza opaco |
+| Separação | Borda em todo card | Sombra, espaço ou dois fundos antes de borda |
+| Botão | Só estado default | hover (sobe sombra) / active (baixa sombra) / focus de marca / disabled |
+| Empty state | Página em branco ou texto de erro | Ilustração + voz + 1 CTA; mesma régua pro 404 |
+| Imagem | Upscale, proporção quebrada, texto ilegível | Só reduzir; `cover`; sombra anti-bleed; overlay pro contraste |
+
+> Fonte: *Refactoring UI* (Adam Wathan & Steve Schoger) e a palestra de Schoger no CSS Day 2019.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "nexus-core-v3",
+  "version": "3.0.0",
+  "type": "module",
+  "description": "Nexus Core v3 — orquestrador de agentes de IA CLI-first (greenfield)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "nexus": {
+    "packageName": "@nexus/core",
+    "slashPrefix": "nexus",
+    "agentNamespace": "nexus"
+  },
+  "scripts": {
+    "gen:version": "node scripts/gen-version.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --import tsx --test packages/contracts/test/*.test.ts packages/config/test/*.test.ts packages/registry/test/*.test.ts packages/governance/test/*.test.ts packages/declarative/test/*.test.ts packages/runtime/test/*.test.ts packages/learning/test/*.test.ts packages/synapse/test/*.test.ts packages/hooks/test/*.test.ts packages/compose/test/*.test.ts packages/validators/test/*.test.ts packages/dist/test/*.test.ts packages/cli/test/*.test.ts packages/orchestration/test/*.test.ts packages/deliberation/test/*.test.ts packages/team/test/*.test.ts packages/squads/test/*.test.ts packages/gateway/test/*.test.ts",
+    "coverage": "node scripts/coverage-summary.mjs",
+    "validate": "node --import tsx packages/cli/src/bin.ts validate",
+    "ratchet": "node --import tsx scripts/ratchet-tighten.ts",
+    "check": "npm run gen:version && npm run typecheck && npm run test && npm run coverage && npm run validate && npm run ratchet",
+    "release:sign": "node --import tsx scripts/release-sign.ts",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "prepublishOnly": "npm run build:bundle"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.28.1",
+    "js-yaml": "^4.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "zod": "^3.23.8"
+  },
+  "dependencies": {},
+  "bin": {
+    "nexus": "bin/nexus.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "agents",
+    "tasks",
+    "templates",
+    "checklists",
+    "knowledge",
+    "squads",
+    "runbooks",
+    "artifact-manifest.json"
+  ]
+}

package/runbooks/campanha-de-conteudo.md

@@ -0,0 +1,36 @@
+---
+id: campanha-de-conteudo
+title: Campanha de conteúdo
+when: produzir uma campanha de conteúdo coordenada com pesquisa, criação e revisão
+---
+
+# Runbook — Campanha de conteúdo
+
+**Cenário (3 linhas):** você precisa de uma campanha de conteúdo (posts, artigos, peças) coordenada,
+não de textos soltos. A pesquisa guia a mensagem, a criação executa e a revisão garante que cada peça
+sustenta a promessa. O squad de conteúdo (Onda 5) é a unidade natural aqui.
+
+## Roster (em camadas)
+
+- **Core (sempre):** analyst (pesquisa/ângulo), pm (direção da campanha)
+- **Squad de conteúdo (Onda 5):** `nexus run --squad conteudo "<missão da campanha>"` — o chief coordena
+  redator, growth, social e analista. Sob demanda: ux-design-expert (peças visuais).
+
+## Execução
+
+1. **Descobrir o ângulo** — `nexus run --mode micro "pesquise dores e linguagem do público <X> sobre <tema>"`
+   → Alex. **Gate:** `discovery-checklist` (público nomeado, dor com evidência). A mensagem parte da dor real.
+2. **Estrategizar a campanha** — `nexus run "defina a mensagem central, os canais e o calendário para <tema>"`
+   → Morgan. **Gate:** `pm-checklist`. Escopo e não-escopo explícitos (o que NÃO entra nesta campanha).
+3. **Produzir** — `nexus run --squad conteudo "produza as peças da campanha <tema> para os canais <lista>"`
+   → o squad executa. Cada peça rastreia à mensagem central (No Invention: nada fora da estratégia).
+4. **Endurecer** — revise cada peça: promessa sustentada, tom coerente, sem alegação sem base. **Gate:**
+   uma reality-check adaptada — evidência da mensagem, não achismo de "ficou bom".
+5. **Lançar** — publique conforme o calendário; instrumente para medir (o que não se mede não se aprende).
+6. **Operar** — `nexus metrics`/analytics do canal → o que engajou vira insumo da próxima Descoberta.
+
+## Sinais de que está no caminho
+
+- Cada peça rastreia à mensagem central — nada publicado "porque ficou bonito".
+- O calendário e os canais foram escolhidos, não improvisados.
+- A campanha é medida; o aprendizado alimenta a próxima.

package/runbooks/feature-em-projeto-existente.md

@@ -0,0 +1,37 @@
+---
+id: feature-em-projeto-existente
+title: Feature em projeto existente (brownfield)
+when: adicionar uma capacidade a um código que já existe e não pode quebrar
+---
+
+# Runbook — Feature em projeto existente
+
+**Cenário (3 linhas):** o código já roda em produção e uma feature nova precisa entrar sem regressão.
+O risco aqui não é construir — é NÃO quebrar o que funciona. O time entende o terreno antes de mexer,
+e o gate de qualidade guarda a porta contra regressão.
+
+## Roster (em camadas)
+
+- **Core (sempre):** architect, dev, qa, devops
+- **Sob demanda:** analyst (mapear o legado), data-engineer (migração), ux-design-expert (UI nova)
+
+## Execução
+
+1. **Entender o terreno** — `nexus run "mapeie a arquitetura e os pontos de integração afetados por
+   <feature>"` → Aria. Sem entender o que existe, "adicionar" vira "quebrar".
+2. **Estrategizar o encaixe** — `nexus run "escreva a story de <feature> apontando riscos de regressão
+   e ACs de não-quebra"` → Morgan/Pax. **Gate:** `story-draft-checklist`.
+3. **Estruturar a mudança** — decida migração e compatibilidade. **Gate:** `foundation-checklist`
+   (dados modelados, reversível). Handoff architect → dev com o spec + as fronteiras a respeitar.
+4. **Construir com rede** — `nexus run --mode sprint "implemente <feature>; NÃO altere contrato
+   público sem teste de compat"` → Dex. **Gate:** `story-dod-checklist` + testes de regressão.
+5. **Endurecer contra regressão** — `nexus run "revise <feature>: prove que o comportamento antigo
+   segue intacto (teste de regressão) e o novo funciona"` → Quinn. **Gate:** `reality-check-checklist`.
+6. **Lançar gradual** — devops sobe atrás de flag/canário, rollback ensaiado. **Gate:** `launch-checklist`.
+7. **Operar** — observe o caminho novo E o antigo; alerta configurado antes do tráfego.
+
+## Sinais de que está no caminho
+
+- Todo bug "corrigido" e todo comportamento antigo têm teste de regressão guardando a porta.
+- A mudança sobe reversível e gradual — nunca 100% de uma vez.
+- Contratos públicos só mudam com teste de compatibilidade.

package/runbooks/mvp-startup.md

@@ -0,0 +1,38 @@
+---
+id: mvp-startup
+title: MVP de startup do zero
+when: uma ideia nova virando o primeiro produto mínimo viável
+---
+
+# Runbook — MVP de startup do zero
+
+**Cenário (3 linhas):** você tem uma ideia e quer o menor produto que prova valor. O time core conduz
+do problema ao lançamento, cortando escopo sem cortar qualidade. O gate de cada fase impede pular
+etapa que volta a cobrar caro depois.
+
+## Roster (em camadas)
+
+- **Core (sempre):** analyst, pm, po, architect, dev, qa, devops
+- **Sob demanda:** ux-design-expert (se tem interface), data-engineer (se tem dados/schema)
+
+## Execução (fases comprimidas → comandos reais)
+
+1. **Descobrir** — `nexus run --mode micro "pesquise o problema X para o público Y e resuma a dor"`
+   → Alex entrega o brief. **Gate:** `discovery-checklist` (problema real + usuário + evidência).
+2. **Estrategizar** — `nexus run "escreva o PRD do MVP para <brief>, escopo mínimo, épicos priorizados"`
+   → Morgan entrega o PRD; Pax valida. **Gate:** `pm-checklist`. Handoff pm → architect.
+3. **Estruturar** — `nexus run "desenhe a arquitetura e o schema mínimos para <PRD>"`
+   → Aria + Dara. **Gate:** `foundation-checklist`. Handoff architect → dev (spec como contrato).
+4. **Construir** — por story: `nexus run --mode sprint "implemente a story <n> seguindo o spec"`
+   → Dex (Uma se houver UI). **Gate:** `story-dod-checklist` (suíte verde, ACs cobertos).
+5. **Endurecer** — `nexus run "revise a story <n>: execute, colete evidência, emita o veredito"`
+   → Quinn. **Gate:** `reality-check-checklist`. Reprovar 2–3× é saudável; FAIL → volta ao Dex.
+6. **Lançar** — delegue ao devops: rollback ensaiado, assinatura verificada, observabilidade de pé.
+   **Gate:** `launch-checklist` (só o Gage faz push/PR/release).
+7. **Operar** — acompanhe métricas (`nexus metrics`) e capture aprendizado para a próxima Descoberta.
+
+## Sinais de que está no caminho
+
+- Cada AC tem teste verde e evidência (sem isso, não é MVP, é demo).
+- Nenhum agente começa frio: os handoffs carregam o contexto entre fases.
+- O escopo cortado está REGISTRADO como "não agora", não esquecido.

package/runbooks/resposta-a-incidente.md

@@ -0,0 +1,37 @@
+---
+id: resposta-a-incidente
+title: Resposta a incidente em produção
+when: algo quebrou em produção e precisa de contenção, correção e aprendizado
+---
+
+# Runbook — Resposta a incidente
+
+**Cenário (3 linhas):** produção quebrou. A ordem é conter primeiro, consertar a causa depois,
+aprender por último — nessa sequência. Pressa que pula a evidência conserta o sintoma e deixa a causa
+viva. O gate aqui é a honestidade: só declara resolvido quem PROVA que resolveu.
+
+## Roster (em camadas)
+
+- **Core (sempre):** devops (comanda), qa, dev
+- **Sob demanda:** architect (causa-raiz sistêmica), data-engineer (corrupção/migração de dados)
+
+## Execução (fases comprimidas — velocidade com método)
+
+1. **Conter** — devops estabiliza (rollback do último release, feature flag off, isolar o blast radius).
+   Rollback ensaiado do `launch-checklist` paga aqui. Contenção NÃO é correção — é parar o sangramento.
+2. **Diagnosticar** — `nexus run --mode micro "investigue a causa-raiz do incidente <descrição> a partir
+   de <logs/sintomas>"` → Dex/Aria. Causa-raiz, não sintoma; hipótese sem evidência não fecha.
+3. **Corrigir** — `nexus run "implemente a correção da causa-raiz + o teste que reproduzia o incidente"`
+   → Dex. **Regra:** o teste que reproduz o bug vem ANTES do fix (red → green).
+4. **Endurecer** — `nexus run "prove que o incidente não se repete: teste de regressão + fluxo exercitado"`
+   → Quinn. **Gate:** `reality-check-checklist`. "Corrigido" sem regressão é hipótese.
+5. **Lançar a correção** — devops sobe com observabilidade reforçada no ponto que falhou. **Gate:**
+   `launch-checklist`.
+6. **Aprender (post-mortem sem culpa)** — registre causa, linha do tempo e a ação que evita a reincidência;
+   alimente a próxima Descoberta. Incidente sem aprendizado capturado volta.
+
+## Sinais de que está no caminho
+
+- A contenção veio antes da correção; ninguém "consertou" com produção ainda sangrando.
+- A correção tem o teste que reproduzia o incidente (red-first), não só o "ajuste".
+- O post-mortem foca no sistema, não em culpados — e vira ação concreta.

package/squads/exemplo-conteudo/agents/editor-chefe.md

@@ -0,0 +1,48 @@
+---
+id: editor-chefe
+name: Élio
+title: Editor-Chefe de Conteúdo Técnico
+icon: 🗞️
+archetype: Orchestrator
+lens: coerência editorial — a pauta certa, na profundidade certa, para o leitor certo
+whenToUse: orquestrar a produção de um artigo técnico (pauta → pesquisa → rascunho → revisão → publicação)
+authority: editor-chefe
+model: opus
+owns:
+  - planejar-pauta
+  - revisar-artigo
+delegatesTo:
+  - { agent: pesquisador, when: "levantar fontes, dados e estado da arte do tema" }
+  - { agent: redator, when: "transformar pesquisa + pauta em rascunho de artigo" }
+  - { agent: devops, when: "git push do artigo aprovado — SEMPRE via devops, sem exceção" }
+---
+
+# Élio — Editor-Chefe de Conteúdo Técnico
+
+## Identidade
+
+Eu sou o Élio, o chefe deste squad de conteúdo. Eu não escrevo o artigo — eu garanto que o artigo
+certo seja escrito. Defino a pauta com ângulo e leitor-alvo explícitos, despacho a pesquisa para o
+Pio, o rascunho para a Rita, e reviso o resultado contra a pauta original antes de qualquer
+publicação. Artigo sem tese não sai da minha mesa.
+
+## Princípios inegociáveis
+
+- **Pauta antes de prosa.** Nenhuma palavra é escrita antes de a pauta declarar tese, leitor-alvo
+  e o que o leitor sai sabendo. Texto sem pauta é divagação com formatação.
+- **Cada afirmação tem fonte.** O que a pesquisa não sustenta, o artigo não afirma. Eu devolvo o
+  rascunho em vez de publicar achismo.
+- **Eu orquestro, não executo.** Pesquisa é do Pio, prosa é da Rita, push é do devops do time core.
+  Meu trabalho é a decisão editorial e o veredito final.
+
+## Como eu trabalho (método)
+
+1. **Defino a pauta** — tese, leitor-alvo e o que o leitor sai sabendo, explícitos antes de tudo.
+2. **Despacho** a pesquisa ao Pio e, com o dossiê pronto, o rascunho à Rita.
+3. **Reviso contra a pauta** — o artigo entregou a tese para o leitor certo, com cada afirmação sustentada?
+4. **Decido a publicação** — aprovo e encaminho o push ao devops, ou devolvo com o que falta.
+
+## Voz
+
+- **greeting:** `🗞️ Élio — editor-chefe. Qual é a tese e para quem?`
+- **closing:** `— Élio, editor-chefe de conteúdo 🗞️`