nexus-core-v3 3.0.0

package/knowledge/web-craft/design-system-from-code.md

@@ -0,0 +1,195 @@
+---
+id: design-system-from-code
+domain: web-craft
+agents: [ux-design-expert]
+when: "ao consolidar um design system a partir de um codebase existente"
+---
+
+# Design system a partir de código — consolidar o que já existe, sem inventar
+
+Codebase real não tem design system. Tem **arqueologia**: três anos de PRs, quatro pessoas com gostos
+diferentes, um copy-paste de Figma que ninguém atualizou, e `#3B82F6` digitado à mão em 47 lugares. O
+trabalho aqui **não é desenhar** — é *auditar, agrupar e migrar* o que está espalhado, transformando
+caos em tokens reutilizáveis **sem quebrar quem consome**. A regra-mãe: **todo token tem que ter
+origem rastreável no código atual.** Você não está criando uma paleta nova — está nomeando a que já
+existe e matando as divergências. Inventar uma cor "mais bonita" no meio da consolidação é trair o
+trabalho: vira redesign disfarçado de auditoria, e ninguém pediu redesign.
+
+## O problema / os tells
+
+Você está diante de um codebase que precisa de design system se vê 3+ destes:
+
+1. **Hex hardcoded espalhado** — `grep -rE '#[0-9a-fA-F]{3,6}'` retorna centenas de hits. O mesmo azul
+   aparece como `#3B82F6`, `#3b82f6`, `#3a83f7` (alguém errou de um dígito), `rgb(59,130,246)` e
+   `rgba(59,130,246,1)`. São "o mesmo azul" pro olho, cinco valores distintos pro computador.
+2. **Escalas tipográficas paralelas** — um componente usa `text-sm/text-base/text-lg` (Tailwind), outro
+   tem `font-size: 15px` cravado, um terceiro herda `1.05rem` de um CSS legado. Três escalas, zero
+   intenção. Você conta 11 tamanhos de fonte distintos numa tela só.
+3. **Spacing ad-hoc** — `margin-top: 13px`, `padding: 18px 22px`, `gap: 6px`. Números que não pertencem
+   a escala nenhuma, nascidos de "arrastar até parecer certo" no DevTools. O tell clássico: `17px`.
+   Ninguém escolhe 17 de propósito.
+4. **Variantes de componente duplicadas** — `Button`, `ButtonNew`, `PrimaryButton`, `CTAButton` e um
+   `<button className="btn-primary">` solto. Fazem a mesma coisa, divergem em 3px de padding e um
+   shade de hover. Cada um foi "mais rápido criar do novo do que achar o que existia".
+5. **z-index sem sistema** — `z-index: 9999`, `z-index: 99999`, `z-index: 100`, `z-index: 9998` (o
+   hack pra "ficar atrás do 9999"). Guerra de empilhamento, não arquitetura de camadas.
+6. **Sombra e raio por gosto do dia** — `box-shadow` com 6 receitas diferentes de blur/spread/opacity;
+   `border-radius` variando entre `4px`, `6px`, `8px`, `0.5rem` e `9999px` sem critério de uso.
+7. **Dark mode meia-boca** — metade dos componentes responde a `.dark`, a outra metade tem branco
+   cravado e "estoura" no tema escuro. Sintoma de cor hardcoded, não tokenizada.
+8. **O Figma e o código discordam** — o token "primary" no design tool é `#2563EB`, no código rodando
+   em produção é `#3B82F6`. A fonte da verdade é o que o usuário vê: **o código em produção**, não o
+   arquivo de design. Comece pelo código.
+
+Anti-tell (o que NÃO é problema): dois valores próximos podem ser **intencionais** — `border` em `1px`
+e divisor em `1px` mas com cores diferentes é correto. Nem toda repetição é dívida; só a **divergência
+sem razão** é. Não tokenize ruído como se fosse sinal.
+
+## Os princípios do craft
+
+### 1. Inventário antes de opinião — meça, não ache
+
+Não comece propondo paleta. Comece **extraindo a verdade** do código com comandos, não com olho:
+
+```bash
+# Cores: todos os hex, normalizados e contados por frequência
+grep -rohE '#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}|rgba?\([^)]+\)' src/ \
+  | tr 'A-F' 'a-f' | sort | uniq -c | sort -rn
+
+# Font-sizes: toda a escala real em uso
+grep -rohE 'font-size:\s*[0-9.]+(px|rem|em)' src/ | sort | uniq -c | sort -rn
+
+# Spacing: padding/margin/gap literais (o que escapou da escala)
+grep -rohE '(margin|padding|gap)[^:]*:\s*[0-9.]+px' src/ | sort | uniq -c | sort -rn
+
+# z-index: o mapa da guerra de empilhamento
+grep -rohE 'z-index:\s*-?[0-9]+' src/ | sort | uniq -c | sort -rn
+
+# Componentes que parecem o mesmo botão
+grep -rlE 'Button|btn' src/components/ | sort
+```
+
+A saída de frequência é ouro: o hex que aparece **89 vezes** é seu primitivo; o que aparece **1 vez** e
+difere por um dígito do primitivo é divergência pra eliminar. Frequência separa o sistema (alto uso,
+intencional) do acidente (uso único, erro de digitação).
+
+### 2. Cluster por proximidade perceptual, não por igualdade exata
+
+`#3B82F6`, `#3b82f6` e `#3a83f7` são **o mesmo token**. Agrupe por distância de cor (ΔE), não por
+string idêntica. Regra prática sem ferramenta: converta pra HSL e agrupe o que está dentro de ~2% em
+cada canal. Cada cluster vira **um** primitivo; a variante mais frequente do cluster é a canônica, as
+outras são aliases a migrar. Mesma lógica pra spacing: `13px`, `14px`, `15px` provavelmente queriam ser
+`16px` — colapse pro valor da escala mais próximo, não preserve o acidente.
+
+### 3. Primitivos → semânticos (duas camadas, nunca uma)
+
+O erro fatal é tokenizar direto pra uso: `$button-blue: #3B82F6`. Quando a marca trocar de azul, você
+caça `button-blue` em 200 lugares. Faça **duas camadas**:
+
+```
+PRIMITIVOS (a paleta crua, sem significado):
+  --blue-500: #3B82F6
+  --blue-600: #2563EB
+  --gray-50:  #F9FAFB
+
+SEMÂNTICOS (o significado, apontando pro primitivo):
+  --color-action:        var(--blue-500)
+  --color-action-hover:  var(--blue-600)
+  --color-surface:       var(--gray-50)
+  --color-text-primary:  var(--gray-900)
+```
+
+Componentes consomem **só semânticos** (`--color-action`), nunca primitivos diretos. Trocar a marca =
+mudar um apontamento. Dark mode = remapear semânticos pra outros primitivos, sem tocar em componente.
+Essa indireção é o que separa um design system de uma lista de cores com nome.
+
+### 4. Nomeie por função, não por aparência
+
+`--color-primary` é fraco (primário de quê?). `--color-danger`, `--color-action`, `--color-surface`,
+`--color-border-subtle` carregam **intenção** — o consumidor sabe quando usar sem ler doc. E nunca
+nomeie pela cor: `--color-green-success` quebra no dia que "sucesso" virar azul. O nome é o contrato;
+a cor é detalhe de implementação.
+
+### 5. Meça consistência com um número, priorize a dívida com ele
+
+"Está inconsistente" não move ninguém. **Tokenization coverage** move: `% de valores que vêm de token
+vs hardcoded`. Calcule por categoria:
+
+```
+cor:        38% tokenizado  → 62% hardcoded   (pior, ataca primeiro)
+spacing:    71% tokenizado
+tipografia: 84% tokenizado
+```
+
+Priorize por **frequência × visibilidade × esforço**: a cor de ação aparece em todo CTA (alta
+visibilidade), tem 62% solto (alto volume) e é troca mecânica (baixo esforço) → primeira da fila. O
+`z-index` aparece em 6 lugares e mexer arrisca regressão de overlay → depois, com cuidado. Não migre
+em ordem alfabética; migre em ordem de retorno.
+
+### 6. Migre com codemod e alias, nunca com find-and-replace cego
+
+Trocar `#3B82F6` por `var(--color-action)` no braço pode quebrar onde aquele azul era **coincidência**
+(um azul de ícone de terceiro que não devia seguir a marca). Migre assim:
+
+1. **Camada de alias primeiro**: defina o token apontando pro valor atual exato. Nada muda visualmente
+   — você só ganhou o nome.
+2. **Codemod scoped**: substitua o literal pelo token **arquivo por arquivo**, rodando o diff visual
+   (ou snapshot de teste) a cada lote. `jscodeshift`/`postcss` com escopo, não sed global.
+3. **Deprecação, não deleção**: o componente velho (`ButtonNew`) ganha um `@deprecated` apontando pro
+   canônico e continua funcionando. Você remove quando os consumidores migrarem — não no mesmo PR.
+4. **Visual regression como rede**: snapshot antes/depois. Se um pixel mexeu e você não previu, a
+   migração não era equivalente — investigue antes de seguir.
+
+A migração correta é **invisível ao usuário**. Se a tela mudou, você fez redesign sem querer.
+
+### 7. Component canônico = consolidar variantes na de maior cobertura, com props
+
+Cinco botões viram **um** `Button` com variantes explícitas — `variant="primary|secondary|ghost"`,
+`size="sm|md|lg"`. A base é a variante de **maior uso real** (a que mais aparece no grep), não a "mais
+nova" nem a "mais bonita". As divergências de 3px que cada um tinha viram ou um token de tamanho, ou
+são apagadas como o acidente que eram. Quem consumia `CTAButton` ganha um alias deprecado
+`CTAButton = (p) => <Button variant="primary" {...p} />` — migra sem PR de breaking change.
+
+### 8. A saída é três coisas, não um arquivo de cores
+
+Entregue: **(a) tokens** em duas camadas, num formato consumível (CSS vars + JSON/W3C design tokens
+pra ferramentas), **(b) componentes canônicos** com variantes e os antigos deprecados apontando pra
+eles, e **(c) doc viva** que mostra cada token e componente *renderizado* (Storybook ou página de
+estilo), com a regra de uso ("use `--color-action` em qualquer elemento clicável primário; nunca
+hardcode azul"). Doc que é só uma tabela de hex morre na primeira semana; doc que renderiza o token e
+diz quando usar é a que segura a consistência depois que você sai.
+
+## Checklist
+
+Antes de declarar o design system consolidado — qualquer "não" é trabalho pendente:
+
+- [ ] Rodei o inventário por **comando** (grep de cor/fonte/spacing/z-index) e tenho a contagem de
+      frequência, não só uma impressão?
+- [ ] Agrupei valores por **proximidade perceptual** (clusters), não por string exata — e cada cluster
+      tem um canônico definido pela frequência?
+- [ ] Os tokens têm **duas camadas** (primitivo → semântico) e os componentes consomem só semânticos?
+- [ ] Os semânticos são nomeados por **função** (`--color-action`), nunca por aparência
+      (`--color-blue`)?
+- [ ] Tenho um **número de cobertura** por categoria e a fila de migração está ordenada por retorno
+      (frequência × visibilidade × esforço), não alfabética?
+- [ ] A migração usa **alias + codemod scoped + deprecação**, com visual regression a cada lote — e
+      nenhum consumidor quebrou?
+- [ ] As variantes duplicadas viraram **um componente canônico** com props, e os antigos têm alias
+      deprecado funcionando?
+- [ ] A saída tem os **três artefatos** (tokens em formato consumível, componentes canônicos, doc viva
+      que renderiza)?
+- [ ] Cada token tem **origem rastreável** no código atual — não inventei cor/spacing "melhor" no meio?
+- [ ] O usuário final **não vê diferença** depois da consolidação (migração invisível)?
+
+## Antes → depois
+
+| Tell (codebase sem sistema) | Craft (consolidação) |
+|---|---|
+| `#3B82F6` digitado em 47 lugares + 4 variantes por erro de dígito | Um cluster perceptual → `--blue-500` primitivo → `--color-action` semântico; aliases migrados por codemod |
+| `--button-blue: #3B82F6` consumido direto nos componentes | Duas camadas: componente usa `--color-action`, que aponta pro primitivo; trocar marca = um apontamento |
+| `margin-top: 13px`, `padding: 18px`, `gap: 6px` (números do DevTools) | Colapsados pra escala mais próxima (`16px`/`8px`); literais fora de escala viram exceção justificada ou somem |
+| `Button`, `ButtonNew`, `PrimaryButton`, `CTAButton`, `.btn-primary` | Um `<Button variant size>` (base = a de maior uso); os 4 antigos são alias `@deprecated` que ainda funcionam |
+| `z-index: 9999 / 99999 / 9998` (guerra de empilhamento) | Escala semântica de camadas: `--z-dropdown: 10`, `--z-modal: 40`, `--z-toast: 60` |
+| "Está tudo inconsistente" (impressão) | "Cor: 38% tokenizado, 62% solto, 89 ocorrências do azul de ação → primeira da fila" (número) |
+| Entrega: um `colors.ts` com 30 hex nomeados | Entrega: tokens 2 camadas (CSS+JSON) + componentes canônicos + doc que renderiza cada token e diz quando usar |
+| Find-and-replace global de `#3B82F6` → quebra o azul de um ícone de terceiro | Alias primeiro, codemod scoped por arquivo, visual regression a cada lote, migração invisível |

package/knowledge/web-craft/intrinsic-css-layout.md

@@ -0,0 +1,420 @@
+---
+id: intrinsic-css-layout
+domain: web-craft
+agents: [ux-design-expert, dev]
+when: "ao montar layouts CSS resilientes e responsivos sem media queries frágeis"
+---
+
+# Intrinsic CSS Layout — os primitives de Every Layout
+
+Baseado em **Every Layout** (Heydon Pickering & Andy Bell). A tese central: pare de
+"desenhar telas" em breakpoints fixos e passe a **compor primitivos de layout** que se adaptam
+ao conteúdo e ao espaço disponível por conta própria. O navegador já sabe fazer layout — o
+trabalho é **declarar restrições, não posições**. Layout intrínseco = o componente decide como
+se arranjar com base no seu próprio conteúdo e no espaço do container, não em quanto mede a
+viewport.
+
+Isto casa direto com o pack `anti-ai-look`: layout editorial, ritmo de espaço com contraste e
+composição que respira são justamente o que os primitives entregam **sem** cair no grid-de-3-cards
+default.
+
+## O problema
+
+Layout "feito por IA / por template" é, na prática, layout **extrínseco**: tudo amarrado a
+breakpoints de pixel (`@media (max-width: 768px)`), larguras fixas, e o mesmo `gap-8` em tudo.
+Os tells técnicos:
+
+1. **Media queries baseadas na viewport** para componentes que deveriam reagir ao *seu* container.
+   O card quebra a 768px mesmo dentro de uma sidebar de 300px — porque olha a tela, não a si mesmo.
+2. **Espaçamento aplicado item a item** (`margin-bottom` em cada elemento, ou `<br>`/divs vazias)
+   em vez de um ritmo declarado uma vez no container.
+3. **Larguras fixas em px** que estouram em telas estreitas ou criam linhas de texto longas demais
+   (medida ruim) em telas largas.
+4. **Centralização por hack** (`margin-left/right` mágicos, `position: absolute` com `left: 50%`
+   sem `transform`, flex aninhado desnecessário).
+5. **Grid rígido de N colunas** que precisa de media query para virar 2, depois 1 — em vez de
+   "encaixe quantas couberem".
+6. **Tudo no mesmo múltiplo de 8** — espaçamento uniforme, sem tensão, robótico.
+
+A consequência: layout que parece o mesmo template em qualquer projeto, frágil em conteúdo real
+(título com 1 ou 7 palavras, lista com 2 ou 40 itens) e cheio de `@media` remendado.
+
+## O conhecimento
+
+### Fundamento 1 — A "lobotomized owl" (`* + *`) para ritmo
+
+O seletor `* + *` ("coruja lobotomizada") aplica margem **só entre** irmãos adjacentes — nunca no
+primeiro nem no último. É a base do espaçamento intrínseco: você declara o ritmo **uma vez** no
+container e ele vale para qualquer quantidade de filhos.
+
+```css
+.stack > * + * {
+  margin-block-start: var(--space, 1.5rem);
+}
+```
+
+`margin-block-start` (não `margin-top`) respeita modo de escrita / direção. Nada de margem no
+primeiro filho → sem colapso de margem indesejado com o container.
+
+### Fundamento 2 — Espaçamento fluido com `clamp()`
+
+Em vez de trocar tamanhos em breakpoints, escale **continuamente** entre um mínimo e um máximo,
+com a viewport como variável no meio:
+
+```css
+:root {
+  /* clamp(MÍNIMO, PREFERIDO-fluido, MÁXIMO) */
+  --space-s:  clamp(0.75rem, 0.69rem + 0.3vw, 0.94rem);
+  --space-m:  clamp(1.13rem, 1.04rem + 0.45vw, 1.41rem);
+  --space-l:  clamp(1.5rem,  1.38rem + 0.6vw,  1.88rem);
+  --space-xl: clamp(2.25rem, 2.07rem + 0.9vw,  2.81rem);
+
+  --step-0: clamp(1rem, 0.95rem + 0.25vw, 1.13rem);   /* corpo */
+  --step-2: clamp(1.41rem, 1.24rem + 0.85vw, 1.91rem); /* h3 */
+  --step-4: clamp(1.95rem, 1.56rem + 1.95vw, 3.05rem); /* h1 */
+}
+```
+
+A escala fluida resolve o tell de espaçamento uniforme: defina poucos passos (`s`/`m`/`l`/`xl`)
+com **contraste real** entre os extremos e use `--space` para parametrizar cada primitive.
+
+---
+
+### Os primitives
+
+Cada primitive é uma classe utilitária componível, parametrizada por custom properties. Não há
+media queries — a adaptação é intrínseca.
+
+#### 1. Stack — ritmo vertical
+
+Injeta espaço **entre** elementos empilhados. O bloco mais usado da web.
+
+```css
+.stack {
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+}
+.stack > * + * {
+  margin-block-start: var(--space, 1.5rem);
+}
+/* "split": empurra o que vier depois do 1º filho pro fim do container */
+.stack > :nth-child(2) {
+  margin-block-end: auto;
+}
+```
+
+Variantes por escala e exceção local (sem reescrever o seletor):
+
+```css
+[class^='stack'] > * { margin-block: 0; }   /* reset de margens herdadas */
+.stack-large > * + * { margin-block-start: 3rem; }
+.stack-small > * + * { margin-block-start: 0.5rem; }
+
+/* exceção: um espaço maior antes E depois de um elemento específico */
+.stack-exception,
+.stack-exception + * { --space: 3rem; }
+```
+
+**Quando:** qualquer fluxo vertical — artigo, formulário, card. O `split` (`margin-block-end: auto`)
+gruda um rodapé/CTA no fim de um card de altura variável.
+
+#### 2. Box — a unidade com padding/borda coerentes
+
+Caixa que **não vaza** em modo de alto contraste (a borda transparente vira visível em
+`forced-colors`).
+
+```css
+.box {
+  padding: var(--space, 1rem);
+  border: var(--border-thin, 1px) solid;
+  /* borda transparente vira visível em forced-colors: acessibilidade de graça */
+  outline: var(--border-thin, 1px) solid transparent;
+  outline-offset: calc(var(--border-thin, 1px) * -1);
+  color: var(--color-light, #fff);
+  background-color: var(--color-dark, #000);
+}
+.box * { color: inherit; }
+/* inversão herda cor/fundo sem hardcode */
+.box.invert {
+  color: var(--color-dark, #000);
+  background-color: var(--color-light, #fff);
+}
+```
+
+**Quando:** card, alerta, qualquer "superfície". Padding fluido via `--space`. Evite raio uniforme
+em tudo (ver `anti-ai-look`): varie por propósito.
+
+#### 3. Center — centraliza e impõe a medida (measure)
+
+Centraliza horizontalmente **e** limita a largura da linha de texto (`measure` ~60ch para leitura
+confortável). Sem container artificial.
+
+```css
+.center {
+  box-sizing: content-box;
+  margin-inline: auto;
+  max-inline-size: var(--measure, 60ch);
+  padding-inline: var(--gutter, 1rem); /* respiro nas laterais */
+}
+/* variante: centraliza também filhos intrinsecamente menores que a measure */
+.center-intrinsic {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+```
+
+**Quando:** wrapper de conteúdo editorial/artigo. `--measure` controla o conforto de leitura; é
+o antídoto pra linhas de 200 caracteres em telas largas.
+
+#### 4. Cluster — agrupar coisas que quebram juntas
+
+Para grupos de itens de tamanhos diferentes que devem **embrulhar** com espaçamento consistente:
+tags, botões de ação, metadados, nav.
+
+```css
+.cluster {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space, 1rem);
+  justify-content: var(--justify, flex-start);
+  align-items: var(--align, center);
+}
+```
+
+**Quando:** lista de tags, toolbar, grupo de botões, badges. `gap` cuida do espaço em qualquer
+quebra de linha — nada de margens negativas modernas.
+
+#### 5. Sidebar — duas colunas que viram empilhadas sozinhas (sem media query)
+
+Conteúdo + barra lateral. A barra mantém uma largura ideal; quando o espaço aperta, **empilha
+automaticamente** via `flex-wrap`. **CSS verbatim de Every Layout:**
+
+```css
+.with-sidebar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1em;
+}
+.sidebar {
+  /* a menor entre 20ch e 33.333%, nunca passando de 100% */
+  flex-basis: clamp(20ch, 33.333%, 100%);
+  flex-grow: 1;
+}
+.with-sidebar > :last-child {
+  flex-basis: 0;
+  flex-grow: 999;          /* devora o espaço restante = vira "conteúdo principal" */
+  min-inline-size: 50%;    /* abaixo disto, embrulha e empilha */
+}
+```
+
+**Quando:** doc + índice, produto + filtros, conteúdo + aside. O `min-inline-size: 50%` é o gatilho
+de quebra — ajuste pra controlar quando empilha. Coloque a `.sidebar` antes ou depois conforme a
+ordem visual desejada.
+
+#### 6. Switcher — horizontal vira vertical num limiar de container
+
+Alterna entre linha e coluna baseado no **container** (não na viewport). **CSS verbatim:**
+
+```css
+.switcher {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space, 1rem);
+  --threshold: 30rem; /* abaixo disto, empilha */
+}
+.switcher > * {
+  flex-grow: 1;
+  /* o truque: valor enorme (empilha) quando container < threshold;
+     negativo/inválido (lado a lado) quando >= threshold */
+  flex-basis: calc((var(--threshold) - 100%) * 999);
+}
+/* quantity query: 5+ itens forçam vertical (não espreme demais) */
+.switcher > :nth-last-child(n+5),
+.switcher > :nth-last-child(n+5) ~ * {
+  flex-basis: 100%;
+}
+```
+
+**Quando:** 2–4 blocos de peso igual (features, passos, colunas de preço) que devem ir lado a lado
+quando cabe e empilhar quando não. Diferente da Sidebar, aqui os itens têm **peso simétrico**.
+
+#### 7. Cover — herói de altura mínima com conteúdo centralizado
+
+Ocupa pelo menos a altura da viewport, centra o conteúdo principal vertical e acomoda
+cabeçalho/rodapé opcionais.
+
+```css
+.cover {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 100vh;          /* prefira 100svh em mobile p/ evitar pulo de barra */
+  padding: var(--space, 1rem);
+}
+.cover > * {
+  margin-block: var(--space, 1rem);
+}
+/* o elemento principal centraliza-se "empurrando" com auto dos dois lados */
+.cover > .principal {
+  margin-block: auto;
+}
+/* header/footer colam nas pontas */
+.cover > :first-child:not(.principal) { margin-block-start: 0; }
+.cover > :last-child:not(.principal)  { margin-block-end: 0; }
+```
+
+**Quando:** hero de landing, splash, tela de login. Use `100svh`/`100dvh` em vez de `100vh` para
+não pular com a barra do browser mobile.
+
+#### 8. Grid — quantas colunas couberem, sem media query
+
+O grid auto-responsivo canônico. As colunas se ajustam ao espaço; o `min()` evita estouro em telas
+estreitíssimas.
+
+```css
+.grid {
+  display: grid;
+  gap: var(--space, 1rem);
+  /* encaixa quantas colunas de >= --min couberem; cada uma estica até 1fr */
+  grid-template-columns: repeat(auto-fit, minmax(min(var(--min, 250px), 100%), 1fr));
+  /* alinha alturas e nivela linhas */
+  align-content: start;
+}
+```
+
+**Quando:** galeria, lista de cards, dashboard. `auto-fit` colapsa trilhas vazias (cards esticam pra
+preencher); troque por `auto-fill` se quiser trilhas vazias preservadas. `min(var(--min), 100%)` é o
+detalhe que impede a barra de rolagem horizontal em telas menores que `--min`.
+
+#### 9. Frame — proporção fixa que recorta o conteúdo
+
+Mantém uma razão de aspecto (16:9, 1:1) e recorta a imagem/vídeo dentro com `object-fit: cover`.
+
+```css
+.frame {
+  aspect-ratio: var(--n, 16) / var(--d, 9);
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.frame > img,
+.frame > video {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}
+```
+
+**Quando:** thumbnail, capa de card, embed de vídeo. `aspect-ratio` é suporte universal hoje — só
+use o velho hack `padding-bottom: 56.25%` se precisar de browsers antigos.
+
+#### 10. Reel — lista que rola na horizontal (carrossel honesto)
+
+Rolagem horizontal com snap, sem JS. Itens mantêm largura própria e transbordam para o lado.
+
+```css
+.reel {
+  display: flex;
+  gap: var(--space, 1rem);
+  overflow-x: auto;
+  overflow-y: hidden;
+  scroll-snap-type: x mandatory;
+  /* esconde a barra mas mantém rolagem por teclado/toque */
+  scrollbar-width: thin;
+  overscroll-behavior-inline: contain;
+}
+.reel > * {
+  flex: 0 0 var(--item-width, auto);  /* não encolhe: preserva largura */
+  scroll-snap-align: start;
+}
+.reel > img { block-size: 100%; flex-basis: auto; width: auto; }
+```
+
+**Quando:** galeria horizontal, "continue assistindo", chips roláveis. Garanta foco/teclado e
+respeite `prefers-reduced-motion` ao animar o scroll.
+
+#### 11. Imposter — sobrepor e centralizar sobre outro elemento
+
+Centraliza um elemento sobre o pai (modal, badge, "esgotado" sobre um produto).
+
+```css
+.imposter {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  transform: translate(-50%, -50%);
+}
+/* variante "contida": nunca ultrapassa o pai, rola se for grande */
+.imposter.contain {
+  --margin: 0px;
+  overflow: auto;
+  max-inline-size: calc(100% - (var(--margin, 0px) * 2));
+  max-block-size: calc(100% - (var(--margin, 0px) * 2));
+}
+```
+
+O pai precisa de `position: relative`. **Quando:** modal/dialog centralizado, selo sobre imagem,
+tooltip. Para conteúdo realmente modal, prefira o elemento `<dialog>` nativo; o Imposter é pra
+sobreposição puramente visual.
+
+### Composição — o todo é maior que as partes
+
+O ganho real é **aninhar** primitives, cada um cuidando de uma dimensão:
+
+```html
+<!-- Center impõe a measure → Stack dá ritmo vertical → Grid encaixa os cards -->
+<div class="center" style="--measure: 70ch;">
+  <div class="stack" style="--space: var(--space-xl);">
+    <h1>Manifesto</h1>
+    <p>…</p>
+    <div class="grid" style="--min: 18rem; --space: var(--space-l);">
+      <article class="box stack">…</article>
+      <article class="box stack">…</article>
+    </div>
+  </div>
+</div>
+```
+
+Nenhuma media query. Cada primitive resolve uma responsabilidade; o conteúdo dita a quebra. Use o
+**contraste de `--space`** entre seções (uma `--space-xl`, outra `--space-s`) para criar o ritmo
+editorial que o pack `anti-ai-look` exige — em vez do `gap-8` uniforme.
+
+## Checklist
+
+Antes de entregar um layout, qualquer "não" é um remendo a corrigir:
+
+- [ ] O espaçamento vertical vem de **um** `* + *` no container, não de margens item a item?
+- [ ] Há **zero** media queries de viewport para coisas que deveriam reagir ao container (usou
+      Sidebar/Switcher/Grid intrínsecos)?
+- [ ] O wrapper de leitura tem `max-inline-size` em `ch` (measure ~60–70ch), não largura em px?
+- [ ] O grid usa `repeat(auto-fit, minmax(min(--min, 100%), 1fr))` — encaixa o que cabe sozinho?
+- [ ] Usei `clamp()` para espaço/tipografia fluida em vez de trocar valores em breakpoints?
+- [ ] As propriedades são lógicas (`margin-block`, `inline-size`, `inset-inline`) e não físicas?
+- [ ] As seções têm **contraste de `--space`** (ritmo), não todas no mesmo múltiplo?
+- [ ] Cover usa `100svh`/`100dvh` (não `100vh`) pra não pular em mobile?
+- [ ] Reel respeita teclado/foco e `prefers-reduced-motion`?
+- [ ] Box mantém a borda transparente via `outline` pra sobreviver a `forced-colors`?
+
+## Tabela de decisão
+
+| Preciso de… | Primitive | Parâmetro-chave |
+|---|---|---|
+| Ritmo entre elementos empilhados | **Stack** | `--space` (use a escala fluida) |
+| Card / superfície com padding e borda coerentes | **Box** | `--space`, `.invert` |
+| Limitar largura de leitura e centralizar | **Center** | `--measure` (~60–70ch) |
+| Agrupar tags/botões que quebram juntos | **Cluster** | `--space`, `--justify` |
+| Conteúdo + barra lateral que empilha sozinha | **Sidebar** | `flex-basis: clamp(...)`, `min-inline-size` |
+| 2–4 blocos simétricos: lado a lado ou empilhados | **Switcher** | `--threshold` (30rem), quantity query |
+| Hero de altura mínima com conteúdo centrado | **Cover** | `min-block-size: 100svh`, `margin-block: auto` |
+| "Quantas colunas couberem" sem media query | **Grid** | `--min`, `auto-fit`/`auto-fill` |
+| Proporção fixa recortando imagem/vídeo | **Frame** | `aspect-ratio`, `object-fit: cover` |
+| Lista que rola na horizontal (carrossel) | **Reel** | `overflow-x: auto`, `scroll-snap` |
+| Sobrepor/centralizar sobre outro elemento | **Imposter** | `position: absolute` + `translate(-50%,-50%)` |
+
+**Sidebar vs Switcher:** Sidebar = pesos **assimétricos** (uma coluna fina fixa, uma elástica).
+Switcher = pesos **simétricos** (todos iguais), tudo lado a lado ou tudo empilhado.
+
+**`auto-fit` vs `auto-fill` no Grid:** `auto-fit` colapsa trilhas vazias e estica os itens
+existentes; `auto-fill` mantém trilhas vazias (itens não esticam pra preencher sozinhos).