@etus/seven-skill 0.1.0-beta.1

package/docs/detector-rules.md

@@ -0,0 +1,605 @@
+# Catálogo de regras do detector Seven
+
+Referência canônica das 35 regras do detector determinístico `@etus/seven-skill`
+(`npx seven detect`). Cada regra tem um ID estável, uma categoria, a
+justificativa de design, um exemplo errado/certo e a referência ao documento
+do design system que a fundamenta.
+
+Este arquivo é gerado a partir do conhecimento de design; a fonte executável
+das regras é `cli/engine/registry/seven-antipatterns.mjs` (catálogo) e
+`cli/engine/rules/checks.mjs` (funções de check). Se divergirem, o código é a
+verdade — atualize este doc.
+
+## Como ler
+
+- **Categoria** — `quality` (drift de design real, problema de a11y) ou `slop`
+  (tell de UI gerada por IA, no sabor Seven).
+- **Engines** — todas as 35 regras rodam nos três engines: `regex` (arquivos
+  de código), `static-html` (arquivos HTML, com a cascata CSS resolvida) e
+  `browser` (URLs vivas via Puppeteer, com `getComputedStyle` real).
+- **Referência** — o documento em `source/reference/` que documenta a regra
+  de design para os agentes de IA. É onde a regra "vive" como guideline.
+- **Exit codes** — `seven detect` sai com `0` limpo, `2` com findings, `1`
+  erro de uso.
+
+## Exemções
+
+Algumas regras pulam código que legitimamente carrega o padrão:
+
+- `non-inter-font`, `fuchsia-in-ui-chrome`, `pure-black-or-white`,
+  `hardcoded-color-not-token` pulam os pacotes internos `@etus/ui`,
+  `@etus/tokens`, `@etus/seven-skill` (resolvidos pelo `package.json` mais próximo).
+- `hardcoded-color-not-token` e `pure-black-or-white` pulam
+  `packages/tokens/sources/` — são os arquivos que *definem* os tokens.
+- Arquivos `.stories.*`, `.test.*`, `.spec.*` e `.md` nunca são escaneados:
+  scaffold de demo/teste e documentação carregam exemplos intencionais de
+  anti-pattern.
+- Fixtures de teste (`/tests/fixtures/`) são sempre escaneadas, sem exemção.
+
+---
+
+## Grounding — token vs heurística
+
+Cada uma das 35 regras tem um veredito de grounding, inspecionável via
+`getRuleGrounding(id)` no registry:
+
+- **`token`** — os dados da regra vêm do snapshot de `@etus/tokens`
+  (`token-data.generated.mjs`, gerado de `tokens.meta.json`). A regra
+  acompanha o design system automaticamente: quando o Figma muda um token e
+  `@etus/tokens` rebuilda, a regra se atualiza no próximo `build:tokens`.
+- **`heuristic`** — a regra reforça um fato de linguagem, um mecanismo de
+  CSS/tooling, um padrão estrutural ou um standard de a11y que nenhum token
+  define. `heuristic` é um veredito deliberado, não uma regra inacabada.
+
+**8 regras token-grounded:** `non-inter-font`, `hardcoded-color-not-token`,
+`raw-tailwind-palette-color`, `pure-black-or-white`, `tiny-text`,
+`radius-mixed-scales`, `pill-on-button`, `bounce-easing`. As outras 27 são
+heurísticas — o veredito honesto da auditoria: nem toda regra de design tem
+um token que a informe (em-dash, vocabulário pt-PT, ratio de contraste WCAG,
+mecânica do Lightning CSS, geometria de a11y).
+
+---
+
+## Regras de texto — fundacionais (1-9)
+
+Detectam drift que aparece direto no código-fonte.
+
+### 1. `non-inter-font` · `quality`
+
+**O que detecta** — uma declaração `font-family` cuja face primária não é
+Inter, JetBrains Mono ou um fallback de sistema.
+
+**Justificativa** — Seven é Inter-only para sans e JetBrains Mono para código.
+Uma face diferente quebra a identidade tipográfica na primeira olhada. Esta
+regra é a *inversão* da `overused-font` do impeccable: o impeccable bane Inter
+por ubiquidade; o Seven a exige.
+
+**Exemplo**
+
+```css
+/* errado */
+.heading { font-family: 'Space Grotesk', sans-serif; }
+/* certo */
+.heading { font-family: Inter, system-ui, sans-serif; }
+```
+
+**Referência** — `source/reference/typography.md`.
+
+### 2. `hardcoded-color-not-token` · `quality`
+
+**O que detecta** — um literal de cor (hex, `rgb()`, `hsl()`, `oklch()`) em
+código de runtime onde existe uma variável CSS de `@etus/tokens`.
+
+**Justificativa** — código de runtime consome `var(--token)`. Cor literal não
+participa do theming (light/dark) e diverge silenciosamente do Figma. Literais
+só são válidos dentro de `packages/tokens/sources/`, onde os tokens nascem.
+
+**Exemplo**
+
+```tsx
+/* errado */
+<div style={{ background: '#19e699' }} />
+/* certo */
+<div className="bg-[color:var(--primary)]" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 3. `raw-tailwind-palette-color` · `quality`
+
+**O que detecta** — uma utility de cor da paleta default do Tailwind
+(`bg-green-500`, `text-neutral-900`, `border-red-200`, `ring-blue-500`).
+
+**Justificativa** — uma classe da paleta Tailwind pinta uma cor que fura
+`@etus/tokens` exatamente como um literal hex faz: a escala de tokens nunca
+vê aquela cor. O detector pegava `#19e699` mas deixava `bg-green-500` passar.
+Token-grounded: cada família de hue mapeia pra um role semântico do Seven, e
+a regra nomeia o token real do snapshot (`bg-green-500` aponta pra
+`--status-success-background`, `text-red-700` pra `--status-destructive-background`).
+
+**Exemplo**
+
+```tsx
+/* errado */ <button className="bg-green-500 text-neutral-900" />
+/* certo  */ <button className="bg-[color:var(--brand-primary-background)]" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`. Exime os pacotes
+internos do Seven e os paths de definição de token, como as outras regras de
+cor.
+
+### 4. `missing-color-type-hint` · `quality`
+
+**O que detecta** — um valor arbitrário Tailwind v4 referenciando um token de
+cor sem o hint `color:` (ex.: `bg-[var(--primary)]`).
+
+**Justificativa** — o Tailwind v4 usa Lightning CSS, que exige type hints para
+valores ambíguos. Sem o `color:`, o valor OKLCH é descartado silenciosamente —
+o estilo simplesmente não aplica e não há erro.
+
+**Exemplo**
+
+```tsx
+/* errado */ <button className="bg-[var(--button-primary-bg)]" />
+/* certo  */ <button className="bg-[color:var(--button-primary-bg)]" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 5. `missing-length-type-hint` · `quality`
+
+**O que detecta** — um `text-[var(--*)]` arbitrário que resolve para um length
+(font-size) sem o hint `length:`.
+
+**Justificativa** — mesma armadilha do Lightning CSS da regra 4, no eixo de
+tamanho de fonte. `text-[var(--x)]` sem hint é dropado.
+
+**Exemplo**
+
+```tsx
+/* errado */ <h2 className="text-[var(--tabs-trigger-base-text)]" />
+/* certo  */ <h2 className="text-[length:var(--tabs-trigger-base-text)]" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 6. `leading-none-with-length-var` · `quality`
+
+**O que detecta** — `leading-none` combinado com `text-[length:var(--*)]` na
+mesma lista de classes.
+
+**Justificativa** — no Tailwind v4 essa combinação zera a `line-height` (vira
+`0px` em vez de `1`), escondendo o texto. É uma armadilha real já documentada
+na memória do projeto. Use `leading-tight`, `leading-snug`, um literal
+`leading-[1.1]`, ou estilo inline.
+
+**Exemplo**
+
+```tsx
+/* errado */ <span className="leading-none text-[length:var(--badge-text)]" />
+/* certo  */ <span className="leading-tight text-[length:var(--badge-text)]" />
+```
+
+**Referência** — `source/reference/typography.md`.
+
+### 7. `fuchsia-in-ui-chrome` · `slop`
+
+**O que detecta** — uma cor fuchsia em chrome de UI (botões, inputs, bordas).
+Permitida dentro de `<svg>` e em elementos com `data-role="chart"`.
+
+**Justificativa** — fuchsia no Seven é exclusiva de gráficos. Em chrome ela
+lê como um acento "AI roxo/magenta" decorativo, não como identidade. A marca
+é mint e lime.
+
+**Exemplo**
+
+```tsx
+/* errado */ <button style={{ background: '#d946ef' }}>Salvar</button>
+/* certo  */ <svg data-role="chart"><circle fill="#d946ef" /></svg>
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 8. `pt-pt-vocab` · `quality`
+
+**O que detecta** — vocabulário de português europeu em chrome pt-BR
+(`ficheiro`, `telemóvel`, `ecrã`, `utilizador`, ...).
+
+**Justificativa** — o copy de produto do Seven é português brasileiro. Termos
+pt-PT quebram a voz e soam estrangeiros para o usuário.
+
+**Exemplo**
+
+```tsx
+/* errado */ <p>Carregue o ficheiro.</p>
+/* certo  */ <p>Envie o arquivo.</p>
+```
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 9. `pure-black-or-white` · `quality`
+
+**O que detecta** — `#000`/`#fff` puro (ou `rgb(0,0,0)`/`rgb(255,255,255)`).
+
+**Justificativa** — Seven usa neutros tintados do ramp OKLCH. Preto e branco
+puros leem como duros e não-refinados; o ramp tintado dá profundidade.
+
+**Exemplo**
+
+```css
+/* errado */ .text { color: #000; }
+/* certo  */ .text { color: var(--foreground); }
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+---
+
+## Regras invertidas / retunadas do impeccable (10-12)
+
+Regras do impeccable que existem no Seven mas com semântica adaptada.
+
+### 10. `side-stripe-border` · `slop`
+
+**O que detecta** — uma `border-left`/`border-right` mais grossa que 1px usada
+como stripe de acento colorido. (Funde as regras `side-tab` e
+`border-accent-on-rounded` do impeccable.)
+
+**Justificativa** — a faixa lateral colorida é o tell mais reconhecível de UI
+gerada por IA. Seven carrega hierarquia com borda completa de 1px
+`var(--border)`, tint de fundo, ícone-líder, ou reestruturando o elemento.
+
+**Exemplo**
+
+```tsx
+/* errado */ <div className="border-l-4 border-l-orange-500" />
+/* certo  */ <div className="border border-[color:var(--border)]" />
+```
+
+**Referência** — `source/reference/spatial-design.md`. *Nota: o detector só
+dispara quando há classe de cor acentuada; um `border-l-2` neutro é um
+divisor estrutural, não um stripe.*
+
+### 11. `gradient-text-decorative` · `slop`
+
+**O que detecta** — texto com gradiente (`background-clip: text` +
+`linear-gradient`).
+
+**Justificativa** — gradiente em texto é decoração, não significado. Seven usa
+cor sólida do ramp OKLCH; ênfase vem de peso e escala, não de gradiente.
+
+**Exemplo**
+
+```tsx
+/* errado */ <h1 className="bg-gradient-to-r from-primary bg-clip-text text-transparent" />
+/* certo  */ <h1 className="text-[color:var(--foreground)] font-bold" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 12. `shadows-not-borders` · `slop`
+
+**O que detecta** — um box-shadow colorido e borrado em superfície escura (o
+"dark glow" da IA), ou um shadow fazendo o papel de chrome de card.
+
+**Justificativa** — Seven dá hierarquia a cards com bordas de 1px. Shadow é
+reservado para overlays (modais, dropdowns, popovers) e o plate do logo.
+
+**Exemplo**
+
+```css
+/* errado */ .card { box-shadow: 0 0 24px rgba(217,70,239,0.4); }
+/* certo  */ .card { border: 1px solid var(--border); }
+```
+
+**Referência** — `source/reference/spatial-design.md`.
+
+---
+
+## Regras universais de qualidade / a11y (13-29)
+
+Boas práticas de design e acessibilidade que valem para qualquer UI.
+
+### 13. `low-contrast` · `quality`
+
+**O que detecta** — texto que não atinge o contraste WCAG 2.1 AA (4.5:1 corpo,
+3:1 texto grande).
+
+**Justificativa** — contraste insuficiente é uma falha de acessibilidade real.
+WCAG 2.1 AA é o baseline obrigatório do Seven.
+
+**Exemplo** — par `var(--muted-foreground)` sobre `var(--background)` não passa
+em corpo; use `var(--foreground)`.
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 14. `gray-on-color` · `quality`
+
+**O que detecta** — texto cinza sobre fundo colorido.
+
+**Justificativa** — cinza fica lavado sobre cor. Use uma sombra mais escura do
+próprio matiz do fundo, ou um foreground quase-branco, para contraste legível.
+
+**Exemplo**
+
+```tsx
+/* errado */ <div className="bg-blue-600 text-gray-400" />
+/* certo  */ <div className="bg-blue-600 text-white" />
+```
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 15. `nested-cards` · `slop`
+
+**O que detecta** — um card dentro de um card.
+
+**Justificativa** — card aninhado cria ruído visual e profundidade excessiva.
+Seven achata a hierarquia: use divisor de seção, lista rotulada, ou `Tabs`.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 16. `monotonous-spacing` · `quality`
+
+**O que detecta** — o mesmo valor de espaçamento usado em todo lugar.
+
+**Justificativa** — padding idêntico em tudo lê como wireframe. O ritmo do
+Seven é intencional: mais apertado dentro de um card, mais solto entre cards,
+mais solto ainda entre seções.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 17. `flat-type-hierarchy` · `quality`
+
+**O que detecta** — tamanhos de fonte muito próximos entre si.
+
+**Justificativa** — escala achatada não cria hierarquia. Caminhe o ramp
+Text/Heading do Seven; combine escala com contraste de peso.
+
+**Referência** — `source/reference/typography.md`.
+
+### 18. `layout-transition` · `quality`
+
+**O que detecta** — animação de `width`, `height`, `padding` ou `margin`.
+
+**Justificativa** — animar propriedades de layout dispara reflow e fica janky.
+Seven anima só `transform` e `opacity`.
+
+**Exemplo**
+
+```css
+/* errado */ .x { transition: width 200ms; }
+/* certo  */ .x { transition: transform 200ms var(--ease-default); }
+```
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 19. `line-length` · `quality`
+
+**O que detecta** — linhas de texto mais largas que ~80 caracteres.
+
+**Justificativa** — linhas longas cansam: o olho perde o início da próxima.
+Use `max-width` de 65ch a 75ch em containers de texto.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 20. `cramped-padding` · `quality`
+
+**O que detecta** — texto colado na borda do container.
+
+**Justificativa** — texto sem respiro dentro de um container com borda ou tint
+lê como apertado. Padding deve escalar com o tamanho da fonte.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 21. `body-text-viewport-edge` · `quality`
+
+**O que detecta** — parágrafo de corpo colado na borda da viewport, sem
+container de padding.
+
+**Justificativa** — texto rente à borda da tela é desconfortável de ler.
+Envolva em container com padding horizontal, ou `max-width` com `mx-auto`.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 22. `tight-leading` · `quality`
+
+**O que detecta** — `line-height` abaixo de 1.3x o tamanho da fonte.
+
+**Justificativa** — leading apertado deixa texto multi-linha difícil de ler.
+O corpo do Seven usa leading 1.5.
+
+**Referência** — `source/reference/typography.md`.
+
+### 23. `skipped-heading` · `quality`
+
+**O que detecta** — níveis de heading pulados (ex.: `h1` direto para `h3`).
+
+**Justificativa** — leitores de tela usam a hierarquia de headings para
+navegar. Pular nível quebra o outline do documento.
+
+**Referência** — `source/reference/typography.md`.
+
+### 24. `justified-text` · `quality`
+
+**O que detecta** — texto justificado sem hifenização.
+
+**Justificativa** — justificar sem hífen cria "rios" de espaçamento irregular
+entre palavras. Use `text-align: left` para corpo.
+
+**Referência** — `source/reference/typography.md`.
+
+### 25. `tiny-text` · `quality`
+
+**O que detecta** — texto de corpo abaixo de 12px.
+
+**Justificativa** — corpo abaixo de 12px é difícil de ler, sobretudo em telas
+de alta densidade. Corpo usa `--text-base` (16px); labels, `--text-xs` (12px)
+no mínimo.
+
+**Referência** — `source/reference/typography.md`.
+
+### 26. `all-caps-body` · `quality`
+
+**O que detecta** — passagens longas de texto em maiúsculas.
+
+**Justificativa** — reconhecemos palavras pela forma (ascendentes e
+descendentes), que o caixa-alta remove. Seven reserva maiúsculas para labels
+curtos de coluna de tabela monoespaçada; corpo é sentence case.
+
+**Referência** — `source/reference/typography.md`.
+
+### 27. `wide-tracking` · `quality`
+
+**O que detecta** — `letter-spacing` acima de 0.05em em texto de corpo.
+
+**Justificativa** — tracking largo quebra os agrupamentos naturais de
+caracteres e desacelera a leitura. Labels do Seven usam Inter no tracking
+default; tracking largo é decisão Display-only.
+
+**Referência** — `source/reference/typography.md`.
+
+### 28. `bounce-easing` · `slop`
+
+**O que detecta** — easing bounce, elastic ou spring.
+
+**Justificativa** — bounce/elastic soam datados. Objetos reais desaceleram
+suavemente. Seven é decelerado e para — sem overshoot em chrome. Use
+`var(--ease-default)` ou `var(--ease-out-quart)`.
+
+**Exemplo**
+
+```css
+/* errado */ .x { animation: bounce 300ms; }
+/* certo  */ .x { transition: transform 200ms var(--ease-default); }
+```
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 29. `everything-centered` · `slop`
+
+**O que detecta** — todos os elementos de texto centralizados.
+
+**Justificativa** — tudo centralizado lê como template. Chrome do Seven é
+left-aligned com assimetria intencional; centralize só superfícies de display
+deliberadas.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+---
+
+## Regras de elemento Seven-específicas (30-35)
+
+Precisam de inspeção do DOM — é a razão de existir dos engines `static-html`
+e `browser`.
+
+### 30. `missing-tactile-press` · `quality`
+
+**O que detecta** — uma afordância clicável (`<button>`, `role="button"`, item
+de lista interativo) sem transição de micro-press baseada em `transform`.
+
+**Justificativa** — o micro-press tátil é system-wide no Seven: toda
+afordância clicável recebe `hover:translate-y-px` + `active:translate-y-0.5` +
+inset shadow. Um botão sem isso lê como morto.
+
+**Exemplo**
+
+```tsx
+/* errado */ <button className="bg-primary" />
+/* certo  */ <button className="bg-primary transition-transform hover:-translate-y-px active:translate-y-0.5" />
+```
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 31. `pill-on-button` · `slop`
+
+**O que detecta** — um `<button>` com `border-radius: 9999` ou `rounded-full`.
+
+**Justificativa** — botões ficam na escala de radius de componente (`md 8`).
+Pill (9999) é para badges, status indicators e avatar triggers — nunca botões.
+
+**Exemplo**
+
+```tsx
+/* errado */ <button className="rounded-full" />
+/* certo  */ <button className="rounded-[var(--radius-md)]" />
+```
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 32. `radius-mixed-scales` · `quality`
+
+**O que detecta** — um radius de escala-componente (4/8/12) misturado com um
+de escala-superfície (16/20/24/32) no mesmo elemento.
+
+**Justificativa** — Seven roda duas pilhas de radius que não são
+intercambiáveis. Misturar as duas produz o drift "quase parece certo" — o
+anti-pattern mais comum do Seven.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 33. `non-lucide-icon` · `slop`
+
+**O que detecta** — um `<svg>` inline que não é um ícone Lucide (Lucide usa
+viewBox 24x24, stroke de 2px, line caps/joins redondos, sem fill).
+
+**Justificativa** — Seven usa o set Lucide exclusivamente. Um SVG com outra
+convenção de stroke quebra a consistência do sistema de ícones.
+
+**Referência** — `source/reference/typography.md`.
+
+### 34. `emoji-in-chrome` · `slop`
+
+**O que detecta** — um caractere emoji dentro de texto de botão, label ou
+heading.
+
+**Justificativa** — chrome do Seven usa ícones Lucide, não emoji. Emoji
+renderiza inconsistente entre plataformas e quebra o tom.
+
+**Exemplo**
+
+```tsx
+/* errado */ <button>🔍 Procurar</button>
+/* certo  */ <button><SearchIcon /> Procurar</button>
+```
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 35. `forbidden-em-dash` · `quality`
+
+**O que detecta** — um em-dash (`—`) ou en-dash (`–`) em copy voltado ao
+usuário.
+
+**Justificativa** — Seven copy usa vírgula, dois-pontos ou quebra de frase. O
+travessão longo lê como prosa gerada por máquina.
+
+**Exemplo**
+
+```tsx
+/* errado */ aria-label={`Menu do usuário — ${name}`}
+/* certo  */ aria-label={`Menu do usuário: ${name}`}
+```
+
+**Referência** — `source/reference/ux-writing.md`.
+
+---
+
+## Regras do impeccable que o Seven NÃO porta
+
+Quatro regras do impeccable foram deliberadamente descartadas — não fazem
+sentido para um design system de produto:
+
+- **`single-font`** — o impeccable pede pareamento de fontes. Seven É
+  single-font Inter por design; o pareamento seria o anti-pattern aqui.
+- **`italic-serif-display`** — Seven não tem face serif. Inválida por
+  construção.
+- **`hero-eyebrow-chip`** e **`repeated-section-kickers`** — tells de landing
+  page de marketing. Seven opera no register `product`, não `brand`.
+
+## Dívida conhecida em `@etus/ui`
+
+Rodado contra o próprio `@etus/ui`, o detector encontra 8 findings reais em
+código que precede estas regras: 4 `side-stripe-border` (stripes coloridos de
+prioridade em KanbanBoard/DashboardBuilder), 2 `gradient-text-decorative`
+(variante gradient do Heading), 2 `forbidden-em-dash`. São reais — corrigir
+significa mexer em `@etus/ui`, fora do escopo do pacote `@etus/seven-skill`. O gate
+de CI dá `--skip` nessas 3 regras com um baseline guard no teste de dogfood.